Ijfw Writing Skills

IJFW Writing Skills -- author a new skill correctly

A skill is a thin loadable trigger surface. The description: is what Claude reads to decide whether to hot-load the body. Get the description wrong and the skill never fires; get the body wrong and the skill misfires when it does fire. This file teaches you to do both right on the first try.

Iron rule: a skill IS its trigger. If the description does not match the words a user would naturally say, the skill does not exist -- it is documentation no one reads.

1. Discovery -- the description is the trigger surface (CSO)

The description: field is the only thing Claude sees at routing time. Treat it like a search-engine snippet, not like a definition.

Shape: start with "Use when ...", end with Trigger: <verbatim phrases>, /<command-name>.

Forbidden words (enforced by scripts/lint/check-skill-descriptions.sh, case-insensitive whole-word): step, steps, phase, phases, mode, modes, workflow, stage, process, sub-skill, skill-name. These signal "the description summarises the body" and cause Claude to skip the body and follow the description shortcut.

Hard cap: 1024 characters. Aim for under 300.

# BAD -- defines the topic, uses forbidden word "process"
description: "Skill for the code review process. Reviews PRs."

# BAD -- workflow summary, uses "phases" and "steps"
description: "Use when reviewing code -- runs three phases, fifteen steps, two passes."

# GOOD -- triggers only, verbatim phrases, slash-command alias
description: "One-line code review comments. Trigger: review, code review, PR review, /ijfw-review"

# GOOD -- "Use when X" + trigger list
description: "Authoring discipline for new IJFW skills. Use when creating a new skill, writing a skill. Trigger: create a new skill, new skill, /ijfw-writing-skills"

2. Frontmatter -- the loadable contract

Required:

• name: -- letters, digits, hyphens only. Must match the directory name. Prefix with ijfw- for IJFW skills.
• description: -- see section 1.

Optional but recommended:

• since: "1.5.0" -- required for all v1.5.0+ skills so version filters can target them.
• allowed-tools: -- explicit tool list. Omit only when the skill truly needs every tool. Be explicit when you can.
• model: -- only when the skill must pin a specific model (rare).
• argument-hint: -- shown after the slash command in the picker.

First line above frontmatter: <!-- IJFW: narration-not-applicable --> (or narration-applicable) -- declares how the skill interacts with the narration hook.

3. Shape -- terse vs structured

Hot-load on trigger, unload when done. Nothing in the body should pretend to be always-loaded -- the user will only see it when the trigger fires.

4. Anti-patterns -- do not ship these

1. Description-as-definition. "Skill for the code review process" tells Claude what the skill IS. Claude needs to know WHEN to load it. Rewrite as "Use when reviewing code. Trigger: review, /ijfw-review".
2. Forbidden workflow keywords in description. step, phase, mode, workflow, stage, process, sub-skill, skill-name -- the lint will FAIL the build. Use trigger phrases instead.
3. Overlap with existing skills. Before writing, list claude/skills/ and read any neighbour whose name or trigger overlaps. Extend an existing skill rather than fragmenting the trigger surface.
4. Embedded prompts for the user to paste. The skill IS the prompt. The user just speaks the trigger -- they should never see "copy this and paste into chat".
5. Undeclared tool dependencies. If the skill calls Bash, Edit, or an MCP tool, either declare them in allowed-tools: or accept inherit-everything. Do not silently assume tools exist.
6. Documentation about the topic. A skill explains how to DO a thing, not how the thing works in the abstract. If you want to teach concepts, write a reference file under references/ and link from a skill that DOES something with the concept.
7. Skill that is really an agent. If the work needs an isolated context window or a different model, write an agent (claude/agents/<name>.md) and dispatch via the Agent tool. Skills are for in-context discipline; agents are for delegated work.