{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreiairatgvh6d4i2e7eb6c7czz5ggqtwabv47zstu3jvbhp2maazegu",
    "uri": "at://did:plc:ws6dhxzqnqxu5aqxt4kd27oc/app.bsky.feed.post/3mkhfsiwcrpi2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreifdtrbiduxqbw4wzzbo6vtkpjp6jx7bfdxeisppp2qxpn6ch6wrdu"
    },
    "mimeType": "image/png",
    "size": 1314000
  },
  "description": "Create a SKILL.md file, drop it in the right folder, and Claude will load it automatically or on demand.",
  "path": "/how-to-add-skills-to-claude-code/",
  "publishedAt": "2026-04-27T06:07:55.000Z",
  "site": "https://allthings.how",
  "textContent": "Skills turn repeated playbooks, checklists, and reference material into reusable instructions Claude Code can pull in when it needs them. A skill is just a directory with a `SKILL.md` file inside, and once it lives in the right folder, Claude either invokes it automatically based on the description or you trigger it directly with a slash command.\n\n⚡\n\nQuick answer: Create ~/.claude/skills//SKILL.md with YAML frontmatter (at minimum a description) followed by markdown instructions. Claude Code picks it up live, no restart needed.\n\n* * *\n\n### Where skills live\n\nThe folder you choose decides who can use the skill. Personal skills follow you across every project on your machine; project skills ship with a single repo and can be committed to version control so the whole team gets them.\n\nScope| Path| Applies to\n---|---|---\nPersonal| `~/.claude/skills/<name>/SKILL.md`| All your projects\nProject| `.claude/skills/<name>/SKILL.md`| This repo only\nPlugin| `<plugin>/skills/<name>/SKILL.md`| Wherever the plugin is enabled\nEnterprise| Managed settings| Everyone in your organization\n\nIf two skills share a name across scopes, enterprise wins over personal, and personal wins over project. Plugin skills are namespaced as `plugin-name:skill-name`, so they never collide. Existing files in `.claude/commands/` still work, but a skill with the same name takes precedence.\n\n* * *\n\n### Build a skill from scratch\n\nEvery skill needs one required file: a `SKILL.md` with YAML frontmatter on top and markdown instructions below. The frontmatter tells Claude when to load the skill; the markdown tells Claude what to do once it's loaded.\n\n**Step 1:** Create the directory in the scope you want. For a personal skill that explains code with diagrams and analogies, run `mkdir -p ~/.claude/skills/explain-code` in your terminal.\n\n**Step 2:** Create `~/.claude/skills/explain-code/SKILL.md` and add the frontmatter and instructions. The `description` field is what Claude reads to decide whether to invoke the skill, so front-load the trigger keywords.\n\n\n    ---\n    name: explain-code\n    description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks \"how does this work?\"\n    ---\n\n    When explaining code, always include:\n\n    1. **Start with an analogy**: Compare the code to something from everyday life\n    2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships\n    3. **Walk through the code**: Explain step-by-step what happens\n    4. **Highlight a gotcha**: What's a common mistake or misconception?\n\n    Keep explanations conversational. For complex concepts, use multiple analogies.\n\n\n~/.claude/skills/explain-code/SKILL.md\n\n**Step 3:** Test it. Either ask something that matches the description (like \"how does this code work?\") and let Claude pick the skill up automatically, or invoke it directly by typing `/explain-code` followed by a file path. Claude Code watches skill directories live, so new and edited skills take effect inside the current session without a restart.\n\n* * *\n\n### Frontmatter fields that matter\n\nOnly `description` is recommended; everything else is optional. The fields below are the ones you'll reach for most often.\n\nField| What it does\n---|---\n`name`| Display name and slash command. Lowercase letters, numbers, hyphens, max 64 characters. Defaults to the directory name.\n`description`| What the skill does and when to use it. Truncated at 1,536 characters in the listing, so put the key trigger first.\n`disable-model-invocation`| Set to `true` if only you should trigger it. Use this for anything with side effects, like deploys or commits.\n`user-invocable`| Set to `false` to hide it from the slash menu. Use for background reference skills.\n`allowed-tools`| Tools Claude can use without prompting while the skill is active, e.g. `Bash(git add *) Bash(git commit *)`.\n`context: fork`| Runs the skill in an isolated subagent context, with no access to your conversation history.\n`agent`| Which subagent type to use when forking. Built-in options include `Explore`, `Plan`, and `general-purpose`.\n`paths`| Glob patterns that limit when Claude auto-loads the skill, e.g. only when working with files matching `src/api/**`.\n\n* * *\n\n### Reference skills vs. task skills\n\nTwo patterns cover most use cases. Reference skills hold knowledge Claude pulls in alongside your current work, like API conventions or style guides. Task skills give Claude a procedure to run end to end, often paired with `disable-model-invocation: true` so the model doesn't decide on its own to deploy something.\n\n\n    ---\n    name: api-conventions\n    description: API design patterns for this codebase\n    ---\n\n    When writing API endpoints:\n    - Use RESTful naming conventions\n    - Return consistent error formats\n    - Include request validation\n\n\nReference skill example\n\n\n    ---\n    name: deploy\n    description: Deploy the application to production\n    disable-model-invocation: true\n    allowed-tools: Bash(git push *) Bash(npm run *)\n    ---\n\n    Deploy $ARGUMENTS to production:\n\n    1. Run the test suite\n    2. Build the application\n    3. Push to the deployment target\n    4. Verify the deployment succeeded\n\n\nTask skill example\n\n* * *\n\n### Pass arguments to skills\n\nAnything typed after the skill name becomes available through `$ARGUMENTS`. Running `/fix-issue 123` on a skill that says \"Fix GitHub issue $ARGUMENTS\" sends Claude the literal string with `123` spliced in. If the skill body doesn't reference `$ARGUMENTS`, Claude Code appends `ARGUMENTS: <your input>` automatically so nothing gets lost.\n\nFor positional access, use `$0`, `$1`, and so on (or the longer `$ARGUMENTS[0]` form). Wrap multi-word values in quotes: `/migrate-component \"search bar\" React Vue` makes `$0` expand to `search bar`.\n\n* * *\n\n### Add supporting files for bigger skills\n\nA skill is a directory, not just a single file. Drop reference docs, templates, examples, or scripts alongside `SKILL.md` and link to them from the main file so Claude only loads them when needed. This keeps the always-loaded description short while letting heavyweight reference material sit on disk until it's actually used.\n\n\n    my-skill/\n    ├── SKILL.md           # Required - main instructions\n    ├── reference.md       # Loaded only when needed\n    ├── examples.md        # Loaded only when needed\n    └── scripts/\n        └── helper.py      # Executed by Claude, not loaded as text\n\n\nSkill directory layout\n\nKeep `SKILL.md` under 500 lines. Anything longer should move into separate files referenced from the main one.\n\n* * *\n\n### Inject live data with shell commands\n\nThe `!`command`` syntax runs a shell command before the skill content reaches Claude, then replaces the placeholder with the output. This is preprocessing, not something Claude executes — the model only sees the rendered result. It's the cleanest way to give a skill access to real-time data like git status, PR diffs, or environment versions.\n\n\n    ---\n    name: pr-summary\n    description: Summarize changes in a pull request\n    context: fork\n    agent: Explore\n    allowed-tools: Bash(gh *)\n    ---\n\n    ## Pull request context\n    - PR diff: !`gh pr diff`\n    - PR comments: !`gh pr view --comments`\n    - Changed files: !`gh pr diff --name-only`\n\n    ## Your task\n    Summarize this pull request...\n\n\nSkill that summarizes a pull request\n\nFor multi-line commands, use a fenced code block opened with ````!`. Admins can disable this behavior across user, project, and plugin skills by setting `\"disableSkillShellExecution\": true` in settings.\n\n* * *\n\n### Run skills in an isolated subagent\n\nAdding `context: fork` to the frontmatter spins up a fresh subagent context for the skill. The skill content becomes the subagent's prompt, and only the summarized result comes back to your main conversation. This keeps your main context clean during heavy research tasks that read dozens of files.\n\nForked skills only make sense when they contain explicit instructions. A reference-only skill with no task will just receive guidelines and exit without doing anything useful.\n\n\n    ---\n    name: deep-research\n    description: Research a topic thoroughly\n    context: fork\n    agent: Explore\n    ---\n\n    Research $ARGUMENTS thoroughly:\n\n    1. Find relevant files using Glob and Grep\n    2. Read and analyze the code\n    3. Summarize findings with specific file references\n\n\nForked research skill using the Explore agent\n\n* * *\n\n### Install skills from the plugin marketplace\n\nIf you don't want to write skills from scratch, Claude Code's plugin system can install bundled skills from a marketplace repo. Inside an active session, type `/plugin` to open the browser, then use the Discover tab to install plugins from the default Anthropic marketplace.\n\n**Step 1:** Add a third-party marketplace if you want community skills. Run `/plugin marketplace add owner/repo` with a GitHub repo path.\n\n**Step 2:** Install a plugin from that marketplace using `/plugin install plugin-name@marketplace-name`. Pick \"User\" scope to install across all projects, or \"Project\" to install only into the current repo.\n\n**Step 3:** Use `/plugin update` to refresh installed plugins, and `/plugin remove <name>` to uninstall. Plugin skills land in `~/.claude/skills/` just like personal skills, but get version management and auto-updates through the marketplace.\n\n* * *\n\n### Verify a skill is loaded\n\nAfter dropping a skill into place, ask Claude \"What skills are available?\" or try invoking it with `/skill-name`. If the skill appears and runs, it's wired up correctly. If nothing happens, check that `SKILL.md` sits directly inside the skill folder (not nested an extra level deep), the YAML frontmatter parses cleanly, and the `name` uses only lowercase letters, numbers, and hyphens.\n\nLive change detection means edits, additions, and deletions inside `~/.claude/skills/` or a project's `.claude/skills/` apply within the current session. The exception is creating the top-level `skills` directory itself for the first time, which requires restarting Claude Code so the watcher can pick it up.\n\n* * *\n\n### Common reasons a skill misfires\n\nIf Claude isn't using a skill when you expect it to, the description usually doesn't match the language you're using in your prompts. Front-load the description with the trigger phrases and verbs your team actually says. If the skill listing has many entries, descriptions get truncated to fit a character budget that defaults to 1% of the context window (with an 8,000-character fallback), so trim each description to the essentials and raise `SLASH_COMMAND_TOOL_CHAR_BUDGET` if needed.\n\nThe opposite problem — a skill triggering too aggressively — gets fixed by tightening the description or adding `disable-model-invocation: true` so only manual `/skill-name` invocations load it.\n\n📝\n\nNote: When you invoke a skill, its rendered SKILL.md enters the conversation as a single message and stays for the rest of the session. Claude Code does not re-read the file later, so write standing instructions rather than one-time steps. After auto-compaction, only the first 5,000 tokens of each invoked skill are re-attached, sharing a 25,000-token combined budget.\n\n* * *\n\n### Sharing skills with a team\n\nFor project-scoped skills, commit `.claude/skills/` to version control. Anyone who clones the repo gets the skills automatically. For skills that should follow people across multiple projects, package them into a plugin and distribute through a shared marketplace repo — teams can then enable the plugin in `.claude/settings.json` and update everyone at once with `/plugin update`. Enterprise admins can lock down which marketplaces are allowed using managed settings.",
  "title": "How to Add Skills to Claude Code",
  "updatedAt": "2026-04-27T06:07:57.363Z"
}