Create Skills

Build skills that trigger correctly, execute reliably, and stay concise.

Core Principles

• Use progressive disclosure:

• Frontmatter (name , description ) for trigger selection.

• SKILL.md body for core workflow.

• references/ for deep details loaded only when needed.

• Keep skills composable: avoid assumptions that this is the only active skill.

• Prefer deterministic scripts for fragile validation logic.

Workflow

• Define 2-3 concrete use cases.

• Draft trigger-strong frontmatter.

• Design reusable resources (scripts/ , references/ , assets/ ).

• Write actionable instructions and error handling.

• Run triggering/functional/performance tests.

• Iterate based on under-trigger/over-trigger signals.

1. Define Use Cases

Capture for each use case:

• User phrasing (what they actually say)

• Intended result

• Multi-step workflow and required tools (built-in and/or MCP)

• Failure points that need guardrails

If use cases are vague, ask targeted follow-up questions before authoring.

2. Frontmatter Design (Most Important)

Write only what is needed to trigger correctly.

Required fields:

• name : kebab-case, matches folder name

• description : include BOTH

• What the skill does

• When to use it (trigger phrases/context/file types)

Description formula:

• [What it does] + [When to use it] + [Key capabilities]

Good pattern:

• "Processes PDF legal documents for contract review. Use when users ask for clause extraction, risk flags, or redline summaries from .pdf contracts."

Bad pattern:

• "Helps with projects."

Precision controls:

• Add negative triggers to reduce over-triggering.

• Mention relevant file types when applicable.

• Keep wording aligned with real user phrases from use cases.

3. Resource Plan

• scripts/ : deterministic checks/transforms used repeatedly

• references/ : large docs, domain logic, variant-specific guidance

• assets/ : templates and artifacts used in outputs

Rules:

• Keep SKILL.md compact; link to references/ .

• Avoid extra docs in skill folder (README.md , changelog, etc.).

4. Instruction Writing

Write imperative, testable steps.

Include:

• Clear step order and dependencies

• Validation checkpoints

• Common errors with concrete fixes

• Example user inputs and expected outputs

For critical checks, prefer scripts over prose-only checks.

5. Test Protocol

Run these three test groups.

A. Triggering Tests

• Should trigger on obvious requests

• Should trigger on paraphrased requests

• Should NOT trigger on unrelated requests

Target benchmark:

• Trigger on ~90% of relevant prompts in a 10-20 prompt suite

B. Functional Tests

Validate:

• Correct outputs

• Tool/API call success

• Error handling paths

• Edge cases

C. Performance Comparison

Compare with vs without skill:

• Number of clarification turns

• Failed tool/API calls

• Token usage

• End-to-end completion quality

6. Iteration Rules

Under-triggering signals:

• Skill does not load when expected

• Users keep manually invoking it

Fix:

• Add clearer trigger phrases and technical terms to description .

Over-triggering signals:

• Skill loads for unrelated requests

Fix:

• Add negative triggers and tighten scope language.

Execution issues:

• Inconsistent outputs, retries, user corrections

Fix:

• Tighten instructions, add explicit validations, and script critical checks.

Troubleshooting Quick Guide

• Upload fails with missing SKILL.md : file must be exactly SKILL.md .

• Invalid frontmatter: verify YAML delimiters --- and valid syntax.

• Invalid skill name: use lowercase kebab-case.

• Skill not followed: move critical instructions to top and make them concrete.

• Slow behavior: move long content to references/ ; reduce enabled skills.

Scaffolding

Scaffold a new skill directory:

Use default path (.agents/skills)

bash scripts/new_skill.sh <skill-name>

Place in .claude/skills directory

bash scripts/new_skill.sh <skill-name> --path .claude/skills

References

• references/checklist.md

• references/prompt-templates.md

• references/patterns.md

• references/source.md : source PDF and extracted principles

• references/trigger-examples.md : trigger/non-trigger examples for description tuning

• references/failure-remedies.md : failure patterns and minimum effective fixes