writing-skillslisted

# Writing a skill A skill is a note to the next agent, written by the one who just paid for the lesson. It earns its place by changing what that agent does — not by describing what the code already says. ## Layout Skills live in `.agents/skills/` and are exposed to Claude Code by a symlink per skill: ```sh mkdir -p .agents/skills/<name> .claude/skills $EDITOR .agents/skills/<name>/SKILL.md ln -s ../../.agents/skills/<name> .claude/skills/<name> ``` Relative symlink, always — an absolute one breaks the moment the repo is cloned, moved, or opened in another Conductor workspace. Check it from the repo root: ```sh ls -l .claude/skills/ # -> <name> -> ../../.agents/skills/<name> cat .claude/skills/<name>/SKILL.md | head -3 ``` `.agents/` holds the real files so other agent runners can be pointed at the same directory; `.claude/skills/` is one runner's view of it. Both are committed. Supporting files sit beside `SKILL.md` in the same directory and are referenced from it by path — a script to run, a template to copy, a reference table too long for the body. Anything the skill tells you to run should be a file you can run, not a snippet to retype. ## Frontmatter ```yaml --- name: kebab-case-matching-the-directory description: What it covers, and the situations that should pull it in. --- ``` `description` is the only thing an agent sees before deciding whether to open the skill, so it is the whole retrieval mechanism. Write it as triggers, not as a title: - Name