Chapter 23 · Writing High-Quality Skills

Chapter goals: Master the SKILL.md body structure conventions, description writing技巧, resource引用 rules, and independently write a production-ready skill you can use immediately.

23.1 "Good vs Bad" Description Comparison

The description is the skill's most critical field — it directly决定 whether the agent loads you at the correct时机. The official对比 example:

# Bad: vague; the agent can\'t判断 the适用时机
description: Helps with PDFs.

# Good: specific, includes trigger phrases
description: >
  Extracts text and tables from PDF files, fills PDF forms, and merges
  multiple PDFs. Use when working with PDF documents or the user mentions
  PDF extraction, form filling, or merging.

Another common mistake is writing a功能说明书 instead of trigger conditions:

# Wrong: describing functionality
description: This skill parses changelog entries and validates them against git commits.

# Correct: describing the trigger scenario
description: >
  Verify CHANGELOG.md entries match git commits since the last tag.
  Use when the user says "check changelog", "validate release notes",
  or is preparing a release.

Memory mnemonic

Write "when to use me," not "what I can do."

23.2 Body Structure Conventions

The SKILL.md body has no强制 format, but the community形成了 four常用 subsections:

---
name: my-skill
description: >
  Trigger phrase here.
---

# My Skill Name

## Setup
One-time initialization steps (e.g. installing dependencies, configuring secrets).

## Steps
Ordered list of steps to执行; each with specific commands or paths.

## Rules
Behavior constraints: what not to do, what must be遵循.

## Examples
1–2 typical input-output examples to help the agent understand期望 behavior.

The Role of the Setup Section

Setup is for one-time configuration; it shouldn't执行 every run:

## Setup
1. Install dependencies: `pip install -r requirements.txt`
2. Set API key: `export MY_API_KEY=sk-xxx`

Writing the Steps Section

Steps should be executable-specific; avoid vague instructions like "analyze the code":

## Steps

1. Find the previous release tag:
   ```bash
   git describe --tags --abbrev=0

2. List commits since that tag (git log <tag>..HEAD --oneline), classify into Added / Changed / Fixed.
3. Read CHANGELOG.md; check every classified commit appears in the unreleased section.
4. Report: output missing entries as a list; if complete, print "OK".

## 23.3 Resource Reference Rules

When referencing external resources in the skill body, **must use paths relative to the skill directory**:

```markdown
# Correct: relative path
See [the reference guide](references/REFERENCE.md) for details.
Run `./scripts/process.sh <input>` to execute.

# Wrong: absolute path (breaks after迁移)
See [/home/user/.pi/skills/my-skill/references/...](...)

The official spec requires:

"Use relative paths from the skill directory."

This means the skill's entire directory can be整体移动 or distributed, and references remain有效.

23.4 Complete Example: changelog-check Skill

Below is a complete, immediately usable skill:

~/.pi/agent/skills/changelog-check/
├── SKILL.md
└── references/
    └── format.md      # Keep-a-Changelog format说明

SKILL.md content:

---
name: changelog-check
description: >
  Verify CHANGELOG.md covers all notable changes since the last git tag.
  Use when preparing releases or the user mentions changelog.
---

# Changelog Check

## Steps

1. Find the previous release tag:
   ```bash
   git describe --tags --abbrev=0

2. List commits since that tag and classify into Added / Changed / Fixed.
3. Read CHANGELOG.md and check every classified commit appears in the unreleased section.
4. Report: missing entries as a list; if complete, print "OK".

Rules

• Do not modify CHANGELOG.md unless explicitly asked.
• Ignore merge commits and chore: commits with no user impact.

References

See references/format.md for the expected Keep-a-Changelog format details.

## 23.5 Verification and Debugging Methods

After writing a skill, how do you确认 it works correctly?

### Method 1: Manual Trigger Test

```bash
# Force-load the skill and执行
/skill:changelog-check v2.1.0

Method 2: Observe the System Prompt

At agent startup,检查 the system prompt for your skill's description:

# Claude Code can打开 the system prompt to view
# Or in the session type /help to查看 the available skill list

Method 3: Check the Load Log

Most tools输出 a log when加载 a skill, including:

• The skill name
• Whether it matched the trigger condition
• The load耗时

Common pitfall

A description that's too broad (e.g. "Helps with code") causes 误触发 — the agent loads your skill even on unrelated tasks, wasting context. The more specific the description, the more精准 the trigger.

Chapter Summary

• The description determines the trigger; write "when to use me" not "what I can do";
• The body建议分 Setup / Steps / Rules / Examples four sections;
• Resource references must use paths relative to the skill directory;
• Test manually with /skill:name;验证 loading by观察 the system prompt.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Regarding the description field of SKILL.md, which写法 most符合 the official建议?

2. When referencing external resource files in the skill body, what is the correct approach?

3. Which field's缺失 causes the skill to被拒绝 loaded?

4. What does the skill's "progressive disclosure"机制 refer to?

🛠️ Hands-on Practice

1. Write a pytest-review skill for this site's pytest tutorial: when the user says "review the tests,"检查 whether the test files follow best practices (rich assertions, fixture naming conventions, etc.).
2. Deliberately write a vague description (e.g. "Helps with testing"); observe whether it's误 triggered on unrelated tasks.
3. Add a references/api.md reference in the skill body;验证 the relative path loads正常.

After completing the exercises, proceed to Next chapter: Skills Ecosystem and Team Governance.