Project Skills and GitHub Sharing

The skill that lives on your machine alone

Personal skills in ~/.claude/skills/ are great for your individual workflow. But when a commit procedure, a code-review checklist, or a migration helper should apply to everyone working on a project, keeping it only on your machine creates a gap. A new team member clones the repo and none of the shared conventions are available in their Claude Code sessions.

The answer is project-level skills committed to version control. They work exactly like personal skills — SKILL.md files, frontmatter, dynamic injection, supporting scripts — but they live inside the repository and travel with it.

Committing skills to a repository

Create a .claude/skills/ directory at the project root and add skill subdirectories to it:

.claude/
└── skills/
    ├── commit/
    │   └── SKILL.md
    ├── code-review/
    │   └── SKILL.md
    └── db-migration/
        ├── SKILL.md
        └── reference.md

Commit these files normally. Anyone who clones the repo and opens Claude Code gets the project skills automatically — no install step, no manual copy. The /commit, /code-review, and /db-migration commands are immediately available.

A workspace trust dialog appears the first time someone opens a project with skills in .claude/skills/. This is a security checkpoint: review the skills before accepting, since allowed-tools in those files can pre-approve tool access for the whole team.

Monorepo nested skills

In a monorepo, individual packages often have their own conventions. Skills support this with nested directories:

apps/web/.claude/skills/
└── deploy/
    └── SKILL.md   →  /apps/web:deploy

packages/api/.claude/skills/
└── deploy/
    └── SKILL.md   →  /packages/api:deploy

When a skill name clashes with another skill at a different level, Claude Code uses the directory-qualified form: /apps/web:deploy and /packages/api:deploy are distinct commands. Typing the unqualified /deploy runs the project-root skill if one exists, and Claude also automatically invokes the nested variant when the files being edited are inside the matching directory.

This means you can work at the monorepo root, ask Claude to deploy something in apps/web/, and Claude picks the right deploy skill for that package without you specifying the qualified name.

Symlinks for DRY skill reuse

When several projects share the same skill, symlinks let you maintain one canonical version without duplicating files:

# Point project skill at a shared location
ln -s ~/shared-skills/commit .claude/skills/commit

Claude Code follows symlinks and reads SKILL.md from the target. If the same target is reachable from more than one path, Claude Code loads the skill once. This works for personal and project skills, though not for plugin skills (which handle symlinks differently via their marketplace infrastructure).

The disableSkillShellExecution warning for teams

Organizations can disable shell injection entirely via the disableSkillShellExecution managed setting. When this policy is active, every !`command` placeholder in a skill is replaced with [shell command execution disabled by policy] instead of running the command. The failure is silent — the skill still loads, but the injected context is missing.

If you are building project skills that rely on dynamic context injection for critical data, document this dependency explicitly in your skill or README. Alternatively, design skills to work without injection where possible — structure the SKILL.md instructions so they still make sense when the injected sections are absent.

Converting to a plugin

Standalone project skills are ideal for team-internal sharing. When you want to distribute beyond your team — to the community, to multiple organizations, to any project — converting to a plugin is the next step.

Scaffold a plugin from your skills directory:

claude plugin init my-dev-toolkit

This creates ~/.claude/skills/my-dev-toolkit/ with a .claude-plugin/plugin.json manifest:

{
  "name": "my-dev-toolkit",
  "description": "Shared development workflow skills",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

Add a skills/ directory inside the plugin folder and move your SKILL.md files there. Skills in a plugin are namespaced: a commit skill in a plugin named my-dev-toolkit becomes /my-dev-toolkit:commit. This prevents conflicts when multiple plugins define skills with the same name.

Test locally by launching Claude Code with the plugin directory: claude --plugin-dir ./my-dev-toolkit. The plugin loads for that session without any install step. Make changes to skill files and run /reload-plugins to pick them up without restarting.

The agentskills.io open standard

Claude Code skills follow the Agent Skills open standard, which means a SKILL.md file written for Claude Code will work in other AI tools that implement the standard. The frontmatter fields Claude Code adds — disable-model-invocation, context: fork, allowed-tools — are Claude Code extensions on top of the base standard. Other tools may ignore these and still execute the markdown body correctly.

This portability matters if your team uses multiple AI tools. A shared skills repository can serve Claude Code users with the full feature set and users of other tools with the base instruction set — one file, multiple tools.