{"slug": "how-to-create-a-skill-in-claude-code", "title": "How to Create a Skill in Claude Code", "summary": "An engineer at broke2builtai.com explains how to create a skill in Claude Code, a feature that allows Claude to autonomously invoke a procedure based on context rather than a user-typed slash command. The skill is defined by a folder with a SKILL.md file containing YAML frontmatter and instructions, and its description is critical for triggering. The post details the setup process and emphasizes writing precise descriptions to ensure the skill fires correctly.", "body_md": "This is a cross-post — the original (and any updates) live at\n\n[broke2builtai.com].\n\nThe first time I watched Claude Code reach for a skill I hadn't told it to use — read a folder, run the script inside it, and hand back the finished thing — the difference from a slash command finally landed. A slash command waits for you to type it. A skill waits for the *situation*. Claude decides. That one shift is the whole feature, and building one takes about five minutes once you know where the file goes.\n\nHere's the entire thing end to end, including the one gotcha that decides whether your skill ever actually fires.\n\nA Skill is a folder with a `SKILL.md`\n\nfile inside it. The Markdown holds instructions; the YAML frontmatter at the top holds a `name`\n\nand a `description`\n\n. That description is doing the most important job in the whole file: Claude reads it to decide, on its own, whether the current task warrants invoking the skill. Nothing else you write matters if the description doesn't get you picked.\n\nThat's the mental model to hold onto: a [custom slash command](https://dev.to/guides/how-to-create-a-custom-slash-command-in-claude-code/) is a prompt *you* trigger by typing `/name`\n\n; a skill is a procedure *Claude* triggers when the context matches. Same reusable-instructions idea, opposite trigger.\n\nTwo locations register, exactly like commands and [subagents](https://dev.to/guides/how-to-use-subagents-in-claude-code/):\n\n`.claude/skills/<skill-name>/SKILL.md`\n\ninside the repo. Committed, so your whole team gets it.`~/.claude/skills/<skill-name>/SKILL.md`\n\nin your home directory. Follows you across every project on your machine.Each skill is its own folder, and the folder name should match the `name`\n\nin the frontmatter. A loose `SKILL.md`\n\nsitting somewhere else won't be picked up.\n\nCreate the folder and the file:\n\n```\n.claude/skills/pytest-runner/SKILL.md\n```\n\nThen write the two-part file — frontmatter, then body:\n\n```\n---\nname: pytest-runner\ndescription: \"Run, generate, or debug pytest tests for this project. Use when the user asks to run the test suite, add tests for a function, or figure out why a test is failing.\"\n---\n\nWhen invoked:\n\n1. Run the suite with `python -m pytest -q` and read the output.\n2. If tests fail, show the failing test names and the assertion, then propose the smallest fix.\n3. When asked to add tests, match the existing style in `tests/` — same fixtures, same naming.\n4. Never mark work done until the suite is green; paste the passing summary line.\n```\n\nThat's a working skill. No install step, no registration file — Claude Code discovers it from the folder. Next time you ask something that matches the description, Claude reaches for it.\n\nIf your skill never fires, the description is almost always why. Claude selects a skill by matching the task against the description text, so a vague `description: helps with tests`\n\ncompetes badly against everything else in context and usually loses.\n\nWrite the description like a trigger list, not a summary. Name the concrete situations, the verbs, and the file types:\n\n`description: Testing helper.`\n\n`description: Run, generate, or debug pytest tests. Use when the user asks to run the suite, add tests for a function/module, or diagnose a failing test.`\n\nThe body can be as long and detailed as you want — that content only loads once the skill is invoked. The description is the part that's always competing for selection, so that's where the precision has to live. This is the same discipline behind [writing a good system prompt for an agent](https://dev.to/guides/how-to-write-a-system-prompt-for-an-ai-agent/): be explicit about *when*, not just *what*.\n\nThe reason a skill beats a slash command for real workflows is that the folder can hold more than instructions. Anything you drop in the skill directory is available to Claude when the skill runs:\n\n```\n.claude/skills/release-notes/\n├── SKILL.md\n├── template.md          # the format to fill in\n└── changelog-parse.py   # a helper the skill runs\n```\n\nReference them from `SKILL.md`\n\nby relative path — \"fill in `template.md`\n\n\", \"run `changelog-parse.py`\n\non the git log\" — and Claude reads or executes them as part of following the skill. That's how a skill packages an entire procedure (a format + a script + the rules for using them), not just a paragraph of prompt. If the script needs a tool that prompts for permission, the same [permission and hooks rules](https://dev.to/guides/how-to-use-claude-code-hooks/) apply as anywhere else in Claude Code.\n\nThree ways to give Claude Code reusable instructions, and they're not interchangeable:\n\n`/review`\n\n, `/deploy`\n\n).The practical rule: standing context goes in CLAUDE.md; a procedure you invoke yourself is a slash command; a procedure Claude should invoke when it sees the trigger is a skill. Getting that split right is what keeps your everyday context lean while still having deep procedures on tap.\n\nBuild the skill small, then watch whether it fires. Ask something that *should* trigger it and see if Claude reaches for it — if it doesn't, tighten the description and try again. That loop takes a couple of minutes and is the only real test that matters, because a skill that never gets invoked is just a Markdown file nobody reads.\n\n*This site runs its own automation on Claude Code and free-tier AI. If you're wiring up cheap models to do real work, we run everything on GLM's free tier through the z.ai Coding Plan (referral link — it funds our compute); a tight SKILL.md is exactly the kind of harness that keeps a cheaper model on rails.*\n\n*Broke to Built is one broke human + AI agents building real software with no budget, writing down every step. This site's tools run on free GLM — z.ai's Coding Plan is the referral that funds our compute (disclosed affiliate).*", "url": "https://wpnews.pro/news/how-to-create-a-skill-in-claude-code", "canonical_source": "https://dev.to/thryx/how-to-create-a-skill-in-claude-code-pih", "published_at": "2026-07-09 21:19:15+00:00", "updated_at": "2026-07-09 22:05:50.394993+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "large-language-models", "ai-agents"], "entities": ["Claude Code", "broke2builtai.com"], "alternates": {"html": "https://wpnews.pro/news/how-to-create-a-skill-in-claude-code", "markdown": "https://wpnews.pro/news/how-to-create-a-skill-in-claude-code.md", "text": "https://wpnews.pro/news/how-to-create-a-skill-in-claude-code.txt", "jsonld": "https://wpnews.pro/news/how-to-create-a-skill-in-claude-code.jsonld"}}