◆ Sparround

Creating your own skill, step by step

The minimum to create a skill: one folder and one SKILL.md. The sequence:

1. Pick the problem — which instructions you keep retyping.

2. Pick the location — personal (~/.claude/skills/) or project (.claude/skills/).

3. Write it — frontmatter plus steps.

4. Test it — both with /name and with a natural request (to check automatic invocation).

5. Refine — fix what didn't work, shorten the body.

Claude Code watches skill directories for changes live — after editing a file you don't need to restart the session.

bash
# 1. A folder for a project skill (shared with the team)
mkdir -p .claude/skills/release-check

# 2. Write SKILL.md (see the example below)
$EDITOR .claude/skills/release-check/SKILL.md

# 3. Try it in the session — no restart needed
#    /release-check

# 4. Once it works, commit it so the team gets it
git add .claude/skills/release-check
git commit -m "Add release-check skill"

A project skill is committed to the repo — that is what turns it into a shared team tool.

Rules for a good skill body:

  • What to do, not how. The agent knows Kotlin; don't teach it Kotlin. Write the steps specific to your project.
  • Checkable steps. Not "improve the code" but "check that every Composable has a @Preview".
  • State the output format. "Write each finding as file:line" makes the output predictable.
  • Draw the boundary. "Don't modify files, only report" — or the opposite.
  • Keep it short. Long reference material goes into a separate file.

Test a skill two ways: by invoking /name (checks the body works) and with a natural-language request (checks the description works). Often the first works and the second doesn't — that is a description problem, not a body problem.

📚 Sources and documentation