skill-authoring（技能创作）

Skill Authoring

TDD for agent instructions. Test, write, shorten.

What Are You Doing?

Use the right reference file for your task:

• extracting-from-sessions.md — Saving knowledge from a work session into a new skill.
• generating-from-docs.md — Creating a new skill by crawling documentation websites.
• skill-lifecycle.md — Updating, deprecating, or archiving an existing skill.
• tool-design.md — Designing tool interfaces and APIs for agents.
• skill-template.md — Copy-paste template for new skills.
• format-spec.md — Frontmatter fields, directory patterns, naming rules, external tool conventions, and content organization.
• platform-guide.md — What each agent platform discovers, loads, and ignores, plus dual-harness compatibility patterns.

*Note: Skill reference files must be resilient to context compaction. If an agent summarizes this routing table, ensure the distinct purpose of each file remains clear.*

Decide Whether to Create

Create a skill when:

• The technique isn't obvious to agents
• The pattern applies across projects
• You'd reference it again in future sessions

Don't create skills for one-off solutions, standard practices, or constraints enforceable with automation.

What to Include

Only instructions that change agent behavior in ways the codebase can't convey on its own.

Write the Description

The description is the activation trigger. Include WHAT and WHEN. Describe triggering conditions only — not the skill's workflow.

# Good — triggering conditions
description: >-
  Create git commits with intelligent file grouping.
  Use when committing changes.

# Bad — summarizes workflow (agents follow this instead of reading the skill)
description: >-
  Use when committing - groups files by concern, writes
  conventional messages, runs pre-commit hooks

Size Budget

Context window is shared. Every paragraph must justify its cost.

Prefer --help over documenting flags. Cross-reference other skills instead of repeating content. One good example beats many mediocre ones.

Structure for Progressive Disclosure

skills/skill-name/
├── SKILL.md         # Core instructions (loaded on activation)
├── references/      # Heavy content (loaded on demand)
├── scripts/         # Deterministic operations (executed, not read)
└── assets/          # Templates, images (used in output, never loaded)

At startup, agents see only name + description (~100 tokens). On activation, SKILL.md loads. References and scripts load only when the agent needs them during execution.

When to split to references/

Split by content type, not just length:

Heuristic: If the skill covers 3+ independent subtopics and an agent only needs one at a time, each belongs in a reference file. SKILL.md routes to the right one.

Don't wait until you hit 500 lines. A 200-line SKILL.md with three unrelated lookup tables is already a candidate for splitting.

TDD Cycle

RED — Baseline

Run a pressure scenario without the skill. Record what the agent did and where it went wrong.

GREEN — Write Minimal Skill

Address the specific failures from RED. Don't add content for hypothetical cases. Re-run — the agent should now comply.

REFACTOR — Shorten

If the agent still fails, the instruction isn't clear enough — rewrite it shorter, not longer. A clear 3-line instruction outperforms a 30-line version. Cut until compliance breaks, then restore the last cut.

Match Specificity to Risk

Anti-Patterns

• Workflow summaries in descriptions (agents follow the summary instead of reading the full skill)
• "When to use" in body instead of description
• Rationalization scaffolding and authority appeals
• Mandatory gates (<HARD-GATE>, "MUST use before ANY...")
• README.md in plugin root (not loaded into agent context)
• Nesting skills under skills/<plugin>/<skill>/ (not discovered)

Reference

• See the What Are You Doing? section above for all reference files.