# Claude how to create a skill: SKILL.md steps for Claude Code > A skill is a folder with one SKILL.md file. Here is where to save it, what goes in the frontmatter, how to test it and what to check when Claude ignores it. URL: https://claudegpt.si/news/claude-how-to-create-a-skill Published: 2026-10-29T15:03:27.529Z Author: ClaudeGPT Si Newsroom Section: Guides Topics: Claude, Claude Code, Anthropic, AI agents, How to Publisher: ClaudeGPT Si ## Key takeaways - A Claude skill is a folder containing a SKILL.md file with a description and instructions, saved in ~/.claude/skills for personal use or .claude/skills in a project. - Claude uses the description to decide when to load a skill, and you can run it yourself with /skill-name. - In claude.ai, a skill is uploaded as a ZIP, with a name up to 64 characters and a description up to 200 characters. Claude how to create a skill comes down to this: write a folder with one file in it, `SKILL.md`, that holds a short description and a set of instructions. Claude Code reads the description, loads the instructions when a request matches, and also lets you run the skill yourself by typing `/skill-name`. This guide covers Claude Code first, then claude.ai, based on the official docs as of October 29, 2026. It is for anyone who keeps pasting the same checklist or procedure into a chat. When you finish, you will have a working skill, you will know where to save it so the right people get it, and you will know what to check when Claude ignores it. ## What a Claude skill is A skill is a `SKILL.md` file of instructions. Anthropic's [Claude Code documentation](https://code.claude.com/docs/en/skills) says to make one when you keep pasting the same instructions into chat. It differs from a `CLAUDE.md` file in one way that matters: a skill's body loads only when the skill is used, so it costs nothing in context until then. Custom commands have been merged into skills. A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy`, and old command files keep working. ## How to create a skill in Claude Code ### 1. Pick where it lives The folder name becomes the skill name. Where you put the folder decides who gets the skill. | Scope | Path | Who gets it | | --- | --- | --- | | Personal | `~/.claude/skills//SKILL.md` | All your projects on this machine | | Project | `.claude/skills//SKILL.md` | Sessions in this repository. Commit it to share it with your team | | Plugin | `/skills//SKILL.md` | Wherever the plugin is enabled, as `/plugin-name:skill-name` | There are also enterprise skills, deployed through managed settings, and nested `.claude/skills` folders that load when a session starts in or below that subdirectory. Don't name a folder `synced`. That name is reserved for skills downloaded from claude.ai. ### 2. Make the folder and the file The docs use a skill that summarizes uncommitted changes as the first example. Create the folder: ```bash mkdir -p ~/.claude/skills/summarize-changes ``` Then save this as `~/.claude/skills/summarize-changes/SKILL.md`: ```markdown --- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. --- ## Current changes !`git diff HEAD` ## Instructions Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes. ``` The line starting with an exclamation mark and a backtick is dynamic context injection. Claude Code runs `git diff HEAD` and puts the output into the skill before Claude reads it. For several commands, open a fenced block with three backticks followed by an exclamation mark. ### 3. Write the description for Claude The frontmatter sits between two `---` lines, and the first `---` must be the first line of the file. All fields are optional, but the docs recommend `description`, because Claude uses it to decide when to apply the skill. Put the main use case first. The `description` and `when_to_use` text together is cut off at 1,536 characters in the skill listing. Other fields you will use most: | Field | What it does | | --- | --- | | `name` | The command name in the `/` menu. Defaults to the folder name | | `disable-model-invocation` | Set to `true` so only you can run the skill. Default is `false` | | `user-invocable` | Set to `false` to hide it from the `/` menu so only Claude uses it | | `allowed-tools` | Tools Claude can use without asking during the turn the skill runs | | `argument-hint` | An autocomplete hint such as `[issue-number]` | | `context` | Set to `fork` to run the skill in a separate subagent | | `paths` | Glob patterns that limit when Claude loads the skill on its own | If the YAML does not parse, the skill still loads, but with no fields set. Unknown field names are ignored without an error. ### 4. Test it Ask something that matches the description: ```text What did I change? ``` Or run it directly: ```text /summarize-changes ``` Claude Code watches the skill folders, so edits apply in the current session without a restart. If you create a brand-new top-level skills folder during a session, run `/reload-skills`. ## How to pass arguments to a skill Put `$ARGUMENTS` in the body to receive everything typed after the command, or use `$0`, `$1` and so on for individual words. The docs give this example: ```markdown --- name: migrate-component description: Migrate a component from one language to another --- Migrate the $0 component from $1 to $2. Preserve all existing behavior and tests. ``` Running `/migrate-component SearchBar JavaScript TypeScript` fills in all three values. Wrap multi-word values in quotes. `${CLAUDE_SKILL_DIR}` expands to the folder that holds the skill, which is how a skill points at its own scripts. ## How to make a skill run only when you say so By default both you and Claude can invoke a skill. For anything with side effects, such as a deploy, turn off automatic use: ```markdown --- name: deploy description: Deploy the application to production disable-model-invocation: true --- Deploy $ARGUMENTS to production: 1. Run the test suite 2. Build the application 3. Push to the deployment target 4. Verify the deployment succeeded ``` Now the skill runs only when you type `/deploy staging`, and its description is not loaded into context at all. ## How to add supporting files Keep `SKILL.md` under 500 lines, the docs advise, and move detail into other files in the same folder: ```text my-skill/ ├── SKILL.md ├── reference.md ├── examples.md └── scripts/ └── helper.py ``` Link to them from `SKILL.md` so Claude knows when to open each one. Scripts are executed, not read into context. The docs also show a skill that bundles a Python script, called with `python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .`, and pre-approves it with `allowed-tools: Bash(python3 *)`. That grant lasts only for the turn in which the skill runs, and your normal permission settings still apply to everything else. ## How to create a skill in claude.ai Claude's help center describes a second route for the Claude apps. Custom skills there are available on Free, Pro, Max, Team and Enterprise plans, and code execution must be turned on. 1. Make a folder for the skill with a skill file in it. The help article spells the file name `skill.md`. 2. Start it with frontmatter. `name` is required and can be up to 64 characters. `description` is required and can be up to 200 characters. 3. Write the instructions in Markdown below it, and add supporting files if you need them. 4. Check that the folder name matches the skill name, then zip the folder. The folder must be at the root of the ZIP, not loose files. 5. Upload the ZIP, then switch the skill on under Customize, then Skills. On Pro, Max and Team plans, Cowork on Claude for Mac can also record a skill instead: you perform the task on screen while narrating, up to about 10 minutes, and Claude proposes a skill from the recording. Outside Claude Code, such as claude.ai uploads and the Skills API, only `name`, `description`, `license`, `compatibility`, `metadata` and `allowed-tools` are allowed in the frontmatter. Other keys cause an error when you upload or package the skill, so strip Claude Code fields like `disable-model-invocation` first. ## Why Claude is not using your skill The troubleshooting section of the docs gives these checks, in order: 1. Make sure the description contains words you would naturally say. 2. Ask `What skills are available?` and confirm the skill is listed. 3. Rephrase the request to sit closer to the description. 4. Run `/skill-name` directly. 5. If the skill sets `paths`, check that the files Claude touches are inside its current working directory. If the YAML is malformed, Claude can still run the skill with `/skill-name` but cannot match it to a request. Start Claude Code with `--debug` to see the parse error. With Claude Code v2.1.233 or later, `claude plugin validate ~/.claude/skills` finds files whose frontmatter does not parse. If a skill fires too often, make the description more specific, or add `disable-model-invocation: true`. If Claude follows a skill at first and then drifts, the docs suggest moving any rule that must hold every time into a hook, and writing judgment-based guidance so it covers the whole task. After the conversation is compacted, Claude Code keeps only the start of an invoked skill, so put the most important instructions at the top and invoke the skill again if needed. With many skills installed, Claude Code can drop some descriptions to fit a listing budget of 1% of the model's context window. Run `/doctor` to see the cost. ## What to do next Start with one skill for one job, and write the description first. The help center's advice for the Claude apps is the same: keep each skill focused on one workflow, give it examples, and test after each change. Treat skills you download from others like scripts and read them before you switch them on. For more on Claude Code, see our [guide to installing Claude Code](https://claudegpt.si/news/claude-code-how-to-install). Anthropic also publishes template skills in its `anthropics/skills` repository on GitHub. The commands and file contents above are quoted from the official documentation. They were not run in a test environment for this guide. ## Frequently asked questions ### Where do Claude Code skills go? Personal skills go in ~/.claude/skills//SKILL.md and apply to all your projects. Project skills go in .claude/skills//SKILL.md in the repository, and committing them shares them with your team. ### How do I run a Claude skill manually? Type a slash and the skill name at the start of your message, such as /deploy staging. Setting disable-model-invocation to true in the frontmatter makes this the only way the skill runs. ### Why is Claude not using my skill? Check that the description has words you would naturally say, that the skill appears when you ask what skills are available, and that the YAML frontmatter parses. Run it with /skill-name to confirm it loads. ### Can I use a Claude Code skill in claude.ai? Yes, by zipping the skill folder and uploading it, but claude.ai accepts only name, description, license, compatibility, metadata and allowed-tools in the frontmatter. Other Claude Code fields cause an error. ## Sources - [Extend Claude with skills](https://code.claude.com/docs/en/skills), Anthropic - [How to create custom skills](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills), Anthropic