AGENT SKILL

writing-skills

How to write SKILL.md files that trigger reliably and teach effectively. Use when creating, improving, or reviewing Claude Code skills.

License 许可
MIT
最近更新
2026-11-01
Stars
★ 3
Forks
1

01 前言 Front Matter

name
writing-skills
version
0.1.0
description
How to write SKILL.md files that trigger reliably and teach effectively. Use when creating, improving, or reviewing Claude Code skills.

03 SKILL.md 正文

Writing Skills

Scope: covers SKILL.md authoring. For agent writing, see [[writing-agents]]. For plugin architecture, see [[writing-plugins]].

1. The Description is Everything

The description field determines when Claude loads this skill. It is not a summary -- it is a trigger mechanism.

Bad (score 55):

description: "Helpful skill for React development"

Good (score 95):

description: "Use when building React components, debugging re-renders, optimizing performance with useMemo/useCallback, or fixing hook dependency arrays"

Description Checklist

Criterion Test
3+ trigger phrases Count distinct action phrases separated by commas
Action-oriented Starts with "Use when..." or "How to..."
Includes tool/framework name The technology name appears explicitly
Matches real queries Would a user's actual question contain any of your trigger words?

Trigger Phrase Construction

Map real user queries to trigger phrases:

User says Trigger phrase to include
"My component re-renders too much" "debugging re-renders"
"How do I memoize this?" "optimizing performance with useMemo/useCallback"
"My useEffect runs in a loop" "fixing hook dependency arrays"
"I need a new component for..." "building React components"

Rule: if you can't list 3 real user queries that match your description, rewrite it.

2. Body Structure

Section Order

  1. Scope note (if related skills exist) -- tells Claude when to use THIS skill vs another
  2. Most commonly needed patterns -- what users ask about 80% of the time
  3. Decision matrices -- when to use A vs B (tables)
  4. Worked examples -- before/after with scores
  5. Common mistakes -- anti-patterns to avoid
  6. References -- links to deep dives

Heading Rules

  • H1 (#): skill title only (one per file)
  • H2 (##): major sections (numbered: ## 1. Section Name)
  • H3 (###): subsections within a major section
  • Never skip heading levels (no H2 followed directly by H4)

Code Examples

Every code example must show the problem, then the solution:

### Bad (breaks on concurrent requests)
` ` `python
global_state = {}  # shared mutable state
` ` `

### Good (request-scoped)
` ` `python
def handler(request):
    state = {}  # local to this request
` ` `

Rules for code examples:

  • Runnable, not pseudocode
  • Contextual -- show enough surrounding code to understand placement
  • Annotated -- comment the critical line, not every line

3. Progressive Disclosure

Keep SKILL.md under 500 lines. Use the file system for depth:

skills/my-domain/my-skill/
  SKILL.md          # core patterns (< 500 lines)
  references/       # deep dives, edge cases, full API docs
    advanced.md
    api-reference.md
  examples/         # working code samples
    basic-setup.ts
    advanced-config.ts
  scripts/          # utility scripts
    validate.sh

When to Extract to references/

Content type Keep in SKILL.md? Extract to references/?
Top 5 patterns everyone needs Yes No
Full API reference (50+ entries) No Yes
Edge cases (< 5% of users) No Yes
Configuration matrix (20+ options) No Yes
Quick decision table (< 10 rows) Yes No

4. Worked Example: Improving a Skill

Before (score 55/100)

---
name: docker-helper
description: "Information about Docker"
version: 0.1.0
---
# Docker Helper

Docker is a containerization platform. Here are some useful commands.

## Commands
- `docker build` - builds an image
- `docker run` - runs a container
- `docker ps` - lists containers

## Dockerfile
A Dockerfile contains instructions for building an image.

## Docker Compose
Docker Compose is for multi-container applications.

Problems:

  • Description is a label, not a trigger mechanism (0 trigger phrases)
  • Body teaches theory Claude already knows from training
  • No code examples showing problem/solution
  • No decision matrices
  • No scope note

After (score 92/100)

---
name: docker-helper
description: "Use when writing Dockerfiles, debugging container networking, optimizing image size with multi-stage builds, or configuring Docker Compose services. Covers build cache, volume mounts, health checks, and compose profiles."
version: 0.1.0
---
# Docker Helper

> Scope: covers Docker CLI, Dockerfiles, and Compose. For Kubernetes deployment, see [[k8s-deploy]].

## 1. Image Size Optimization

### Before (1.2 GB)
` ` `dockerfile
FROM node:20
COPY . .
RUN npm install
RUN npm run build
CMD ["node", "dist/index.js"]
` ` `

### After (148 MB -- 88% smaller)
` ` `dockerfile
FROM node:20-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:20-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]
` ` `

Key changes: multi-stage build, slim base, copy only production artifacts.

## 2. Base Image Selection

| Use case | Base image | Size |
|----------|-----------|------|
| Node.js production | node:20-slim | 180 MB |
| Node.js minimal | node:20-alpine | 130 MB |
| Python production | python:3.12-slim | 150 MB |
| Static files only | nginx:alpine | 40 MB |
| From scratch (Go/Rust) | scratch | < 20 MB |

Changes made:

  1. Description: 0 trigger phrases -> 8 trigger phrases (+37 points)
  2. Scope note added (+5 points)
  3. Replaced theory with problem/solution examples (+25 points)
  4. Added decision matrix (+10 points)
  5. Removed content Claude knows from training (-15 lines, +5 points for conciseness)

5. Common Mistakes

Mistake Why it hurts Fix
Description is a feature list Claude can't match user queries to the skill Rewrite as trigger phrases starting with "Use when..."
Body teaches theory Wastes tokens on content Claude already knows Show patterns and decisions, not definitions
Over 500 lines Bloats context window, penalized by linters Extract to references/, keep core patterns only
No scope note Claude doesn't know when to use THIS skill vs a related one Add scope note referencing related skills
Pseudocode examples Not actionable, can't be copy-pasted Use runnable code with enough context
Every section has equal weight Buries the most useful content Lead with the 80% patterns, push edge cases to references/

6. Quality Checklist

Before shipping a skill, verify:

  • [ ] Description has 3+ specific trigger phrases
  • [ ] Description starts with "Use when..." or "How to..."
  • [ ] Scope note present (if related skills exist)
  • [ ] H2 sections numbered, H3 subsections under them
  • [ ] Code examples show problem then solution
  • [ ] Decision tables for A-vs-B choices
  • [ ] Total lines < 500
  • [ ] No content Claude already knows from training
  • [ ] At least one worked example with before/after

04 同仓库更多 Skills

shengdabai
shengdabai/Tony-Claude-Code-Skills

seedance-prompt-en

Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

onepage-pdf

Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

native-feel-cross-platform-desktop

Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

fireworks-tech-graph

Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3