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