sammcj/skill-creator-primer

Skill Creator Primer

Note: If your environment does not have the skill-creator skill: Stop and ask the user to run /plugin marketplace add anthropics/skills then skill-creator@claude-plugins-official before proceeding.

How Skills Actually Work

Understanding these mechanics helps you design more effective skills.

Skills are prompt-based context modifiers, not executable code. When invoked, a skill:

1. Injects instructions into the conversation context (via hidden messages to the agent)
2. Modifies execution context by changing tool permissions and optionally switching models
3. Guides the agent's behaviour through detailed instructions

Skill selection happens through pure LLM reasoning. No algorithmic matching, keyword search, or intent classification. The agent reads skill descriptions in the Skill tool's prompt and uses language model reasoning to decide which skill matches. This makes the description field the single most critical element.

Agents tend to under-trigger skills. To combat this, make descriptions slightly assertive about when to activate. Instead of "Build dashboards for data", write "Build dashboards for data. Use this skill whenever the user mentions dashboards, data visualisation, metrics, or wants to display any kind of data."

Progressive disclosure keeps context lean. Three-level loading:

1. Metadata (name + description) - Always in context (~20-100 words)
2. SKILL.md body - Loaded only after triggering (<5k words)
3. Bundled resources - Loaded by the agent as needed (unlimited, scripts execute without reading)

The description must be both concise (to fit token budgets shared with all other skills) and comprehensive (to enable accurate selection).

Degrees of Freedom

Match specificity to the task's fragility and variability:

High freedom (text instructions): Multiple approaches valid, decisions depend on context, heuristics guide approach.

Medium freedom (pseudocode/parameterised scripts): Preferred pattern exists, some variation acceptable, configuration affects behaviour.

Low freedom (specific scripts, few parameters): Operations fragile and error-prone, consistency critical, specific sequence required.

Think of Claude exploring a path: a narrow bridge with cliffs needs guardrails (low freedom), an open field allows many routes (high freedom).

Claude Code Frontmatter Extensions

These are Claude Code-specific fields not covered by the Agent Skills spec. Only include when specifically needed:

• when_to_use: Extra triggering context appended to the description in the skill listing (trigger phrases, example requests). Counts toward the 1,536-character description cap. Only include if the description alone underspecifies triggering
• argument-hint: Hint shown during autocomplete for expected arguments, e.g. [issue-number] or [filename] [format]. Only include if the skill accepts arguments
• arguments: Named positional arguments for $name substitution in the skill body. Accepts a space-separated string or a YAML list; names map to positions in order. Only include if the skill uses named substitutions
• model: Override the model. Set to "inherit" (default) or a specific model ID like "claude-opus-4-7". Only include if the user requests it
• effort: Override effort level when the skill is active. Options: low, medium, high, max. Only include if the user requests it
• context: Set to "fork" to run in a forked sub-agent context. Useful for skills with extensive exploration or large outputs. Only include if the user requests it
• disable-model-invocation: Set to true to prevent Claude from auto-loading the skill. Use for side-effect workflows the user should trigger manually. Only include if the user requests it
• user-invocable: Skills appear as slash commands by default. Set to false to hide from the menu. Only include if the user requests it
• agent: Specify agent type (e.g., "task"). When omitted, runs in current agent context. Only include if the user requests it
• allowed-tools: Space-delimited pre-approved tools. Scope where possible, e.g. "Read Write Bash(uv run scripts/*.py *) Grep WebFetch(domain:code.claude.com)"" (don't use the deprecated : syntax, e.g. Bash(command:*), instead use Bash(command *))
• disallowed-tools: Tools removed from the available pool while the skill is active (clears on the next user message). Use for autonomous skills that must never call a tool, e.g. AskUserQuestion in a background loop. Only include if the user requests it

Token Budget Guidance

The context window is a shared resource. Only add context the agent (current generation frontier models such as Claude Opus/Sonnet) doesn't already have. Challenge each piece: "Does the agent really need this?" and "Does this justify its token cost?"

If the ingest CLI tool is available, use ingest *.md to estimate token usage:

| Rating | Tokens | |--------|--------| | Great | 1k-5k | | Good | 5k-9k | | OK | 9k-12k | | Poor | 12k+ |

Aim for <4k tokens in the main SKILL.md. Move detailed content to reference files.

What to Not Include in a Skill

Skills should only contain files that directly support functionality.

DO NOT create:

• README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_START.md, SUMMARY.md
• User-facing documentation or setup procedures
• Context about the creation process itself
• Fluff, filler, otherwise inconsequential content that doesn't support execution of the skill's function
• A table of contents or index of the skill content within the same file
• Content that an agent could easily infer or would know to access without the skill
• Rich file formats (e.g. zip, pptx, png, pdf etc.) unless they're a template (AI is most efficient with text and tools, bundled file formats add overhead and complexity)

The skill is for an AI agent to do the job. Auxiliary documentation adds clutter and wastes context.

Capture Intent from Conversation

When a user says "turn this into a skill", extract the workflow from the current conversation before asking questions. Look for:

• Tools used and the sequence of steps taken
• Corrections the user made along the way
• Input/output formats observed
• Patterns that repeated across the conversation

Fill gaps with the user, then proceed to skill creation.

Self-Review Protocol

After creating or updating a skill, always perform a critical self-review:

1. Check for duplicated information across SKILL.md and reference files
2. Remove low-value prose, filler, and fluff
3. Thin the language - make important information prominent while reducing word count
4. Verify the description is concise (short) yet comprehensive enough for triggering
5. Ensure no extraneous files were created
6. Frame guidance positively to avoid the pink elephant effect (see Writing Tips). Rewrite "don't do X" as "do Y", or pair the prohibition with the concrete alternative

Verbosity is not rewarded - knowledge quality is.

Writing Tips

Don't state the obvious. the agent already knows a lot about coding and has default opinions. Focus skill content on information that pushes the agent out of its normal way of thinking. If the agent would do the right thing without your skill, that content is wasting tokens.

Build a Gotchas section. The highest-signal content in any skill is a Gotchas section listing common failure points the agent hits when using the skill. Build this up from real failures over time. A good Gotchas section often delivers more value than pages of general instructions.

Avoid railroading the agent. Because skills are reusable across many different prompts and contexts, being too specific in instructions backfires. Give the agent the information it needs, but leave flexibility to adapt to the situation. Overly rigid instructions (heavy MUSTs, exact step sequences) break when the context shifts even slightly.

Think through the setup. Some skills need user-specific configuration (e.g. which Slack channel, which database, API keys). Pattern: on first run, check for a config file; if missing, ask the user and store their answers. This avoids hardcoding values that differ per user or environment.

Avoid pink elephant guidance. Naming specific unwanted behaviour activates it. For example saying "Never use the word delve" may plant the concept and result in the AI using it. Prefer positive instructions stating the desired behaviour. If you must prohibit something, pair it with the concrete alternative so the agent has somewhere to land. Specific banned-item lists (e.g. exact phrases to avoid) are fine when paired with replacements.

Do not add inline scripts within markdown, single commands / simple one liners are fine, but scripts should be their own files.

Gotchas

Upstream validators have an incomplete frontmatter allowlist. The skills-ref library (and the skill-creator's quick_validate.py) only recognise the six Agent Skills spec properties (name, description, license, allowed-tools, metadata, compatibility) and will error on every valid Claude Code extension field (when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, disallowed-tools, model, effort, context, agent). The bundled scripts/validate_skill.py errors only on genuine spec violations and downgrades unknown-field detection to a warning, so documented extensions pass clean and a field newer than the linter won't block. If you instead run quick_validate.py or raw skills-ref and it fails only on one of these fields, the skill is still valid. The official docs at https://code.claude.com/docs/en/skills#frontmatter-reference are the authoritative, version-current list.

Validating a Skill

Validate against the official Agent Skills specification:

uv run scripts/validate_skill.py <skill-directory>

---

Reference agent skills specification (only use if required): https://agentskills.io/specification