Claude Code guide in three levels, Beginner to Advanced: hands-on lessons with checked exercises, every volatile fact cited to its source. Independent community guide.
Turn a repeated workflow into a skill
Intermediate · Lesson 1 of 8 · about 20 minutes · Needs: Intermediate index · Verified against Claude Code v2.1.308 (stable) on 2026-10-25
Goal
By the end of this lesson you can turn a workflow you keep repeating into a project skill, choose which requests should load it, and review the change it produces.
You need
- One of your own repositories with a test command and no uncommitted changes, and your copy of the practice template with Node.js LTS: the check runs from the copy. To practice in the template copy instead, use it for both. Set up the repository's
.practice/folder as the Intermediate index describes, if you haven't yet. - Usage: light to moderate. The Your turn builds one small feature.
[!NOTE] From this level on, the lessons are written for macOS, Linux and WSL 2. On Windows, run Claude Code inside WSL 2 (Set up on Windows): native Windows has no sandbox, which lesson 4 uses, and the hooks in lesson 5 are bash scripts.
The idea
Write a skill when you paste the same playbook into chat for the third time (Build your setup over time). A skill is a folder holding a SKILL.md file: YAML frontmatter that says what the skill is for, then the instructions Claude follows. A project skill lives in .claude/skills/<name>/SKILL.md. Commit it, and everyone who works in the repository gets it.
Claude decides whether to load a skill from its description, plus any when_to_use text, in the skill listing, not from the skill body (Frontmatter reference). Invoking the skill loads the full instructions:
flowchart LR
accTitle: Two ways a skill runs
accDescr: You invoke a skill by name, or Claude matches a request to its listing. Either way Claude Code loads the full skill instructions.
A["You type /five-whys and a problem"] --> C["Claude Code loads SKILL.md"]
B["Claude matches your request to the skill listing"] --> C
C --> D["Claude follows the instructions"]
$ARGUMENTSreceives the text after the skill's name (Pass arguments to skills).- Each skill Claude can load on its own sits in the skill listing, which adds to your context on every turn.
disable-model-invocation: truemakes invocation manual and keeps the description out. Use it for a workflow with side effects or whose timing you must control, such as a commit or a deploy (Control who invokes a skill).
Worked example
In your repository, create the skill's folder and download this guide's example skill,
five-whys. Read it before you use it:mkdir -p .claude/skills/five-whys curl -fsSL https://raw.githubusercontent.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/main/examples/intermediate/01-first-skill/dot-claude/skills/five-whys/SKILL.md -o .claude/skills/five-whys/SKILL.mdWithout its header comments, it starts:
--- name: five-whys description: Finds the root cause of a bug, failure or recurring problem by asking "why" until the answer is a cause you can fix. Use when the user asks why something keeps happening, or wants the root cause rather than a quick fix. argument-hint: "[problem]" --- Find the root cause of this problem: $ARGUMENTSfollowed by the investigation steps and the rule "Don't change any files."
Start
claudein the repository and run/skills(Commands). If the workspace trust dialog appears, trust only a repository you own or have reviewed. The list includesfive-whys, a project skill because it lives in.claude/skills/(Choose where skills load).Run the skill by name, with a problem from your repository. For example, in the practice copy:
/five-whys npm run linkcheck -- samples exits with code 1Read the reported chain, root cause and proposed fixes. Your wording will differ. In a terminal in your repository, run
git status --short: only the downloaded skill should be new. Investigate any code edit before proceeding; this skill tells Claude to change nothing.Run
/clear, then ask a question that matches the description without naming the skill. For example, in the practice copy:Why does the test suite pass even though samples/guide.md has a broken link? I want the root cause, not a quick fix.Look for a
Skilltool call forfive-whysbefore the investigation (Tools reference). If it does not appear, compare the request with the description, revise the request and try in a cleared conversation.
Your turn
The team wants a test-first workflow for requested features, while explanation-only questions should stay read-only. Make test-first load for feature requests, never for questions, and leave the commit to you.
Download the partial
tddskill and read it:mkdir -p .claude/skills/tdd curl -fsSL https://raw.githubusercontent.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know/main/examples/intermediate/01-first-skill/dot-claude/skills/tdd/SKILL.md -o .claude/skills/tdd/SKILL.mdThe frontmatter has
description: TODOanddisable-model-invocation: true, and the Green and Refactor steps are unfinished. The skill ends by showing the diff, not by committing.Decide which requests should load this skill before you edit it. Write the description for requested feature work; keep explanation-only questions outside its stated scope. The skill stops at a diff you review, so it has no side effect that needs a manual trigger, and it can load on its own.
In your editor, finish it:
- replace
TODOin the description with what the skill does followed by "Use when" and the feature requests it fits; - write the Green and Refactor steps, keeping the Red step's style;
- delete the
disable-model-invocation: trueline so this skill can load automatically as well as run by name.
- replace
Commit both reviewed skills with git add and git commit:
git add .claude/skills/five-whys .claude/skills/tdd git commit -m "Add project skills"Run
git status --shortand resolve any remaining lesson changes before continuing.In a session, run it by name on a small feature your repository needs. For example, in the practice copy:
/tdd a slugify(heading) function in src/slug.js that turns a Markdown heading into its link anchor: lowercase, punctuation dropped, spaces turned into hyphensKeep auto mode. Read the failing test output, the passing run and the complete diff. After Claude responds, Claude Code can suggest your next prompt; start typing to dismiss a suggestion you don't want, because the commit is yours to make (Prompt suggestions). If the change is what you asked for, commit the test and the code together in a terminal in your repository, then save that commit:
git rev-parse HEAD > .practice/i-1-commit.txt.Probe the trigger both ways: on a request the skill should load for, and on one it shouldn't (Evaluate and iterate on a skill). Run
/clearand ask for another small feature test-first without naming the skill, such asAdd a countHeadings(markdown) function, test-first.PressEscas soon as theSkilltool call fortddappears, before it starts editing (Interactive mode). Run/clearagain and ask a question, such asExplain how isExternal decides that a link is external.NoSkillcall fortddshould appear.If either probe fails, revise the description, commit it and repeat both. Then run
git status --shortand undo anything the probes changed, so the repository is clean.
Check
You are done when all of these are true:
- The finished skill is committed with no TODO left:
git grep -n TODO HEAD -- .claude/skills/tddprints nothing. - It can run as
/tddand load on its own:git show HEAD:.claude/skills/tdd/SKILL.mdshows a description of what it does and when to use it, and nodisable-model-invocation: true. - The commit saved in
.practice/i-1-commit.txtholds a test and the code it tests:git show --stat $(cat .practice/i-1-commit.txt)lists both. - Self-check (not tested):
/tddran the skill, a cleared conversation loadedtddon its own for a feature request, and a question didn't loadtdd.
Run npm run check -- i-1 --dir <your repo> from your practice copy, or npm run check -- i-1 in the copy itself.
If the skill isn't committed, run git check-ignore -v .claude/skills/tdd/SKILL.md: an ignore rule that matches .claude, in a .gitignore, .git/info/exclude or your global excludes file, hides the folder from git add, so add the file with git add -f. If the invocation item fails, rewrite the description as what the skill does followed by "Use when" and the feature requests it fits, then commit again. If the commit item fails, run /tdd on a new small feature, review the diff, and commit the test with the code before you save that commit.
Watch out
- A skill can pre-approve tools with
allowed-tools, even in aclaude -prun in a folder you've never trusted (Pre-approve tools for a skill). Read the skills in a repository before you run Claude Code there. - If
.claude/skills/didn't exist at session startup, run/reload-skills, and repeat it after each later change there (Edit a skill during a session). After editing an invoked skill, invoke it again to load the changed instructions (Skill content lifecycle).
Go further
- Introduction to agent skills: Claude Academy's course on writing and sharing skills.
- Agent Skills: the open standard that Claude Code skills follow, which works across other AI tools too.
- Extend Claude with skills: every frontmatter field, arguments, supporting files and running a skill in a subagent.
Sources: Extend Claude with skills · Extend Claude Code · Advanced setup · Commands · Security · Tools reference · Interactive mode · git-status · git-add · git-commit · git-rev-parse
← Intermediate index · Organize project memory and see what loaded → · Topic: Skills · Stuck on this lesson?