入门必看入门

怎么写一个自定义 Skill？

手把手写一个 Skill——从文件结构、配置格式到测试发布。

📋 SKILL.md 完整代码

---
name: custom-skill
description: >-
  手把手写一个 Skill——从文件结构、配置格式到测试发布。
  Use when working on custom skill tasks.
allowed-tools: Read,Write,Bash
---

# 怎么写一个自定义 Skill？

## Quick Start
1. Save as `~/.claude/skills/custom-skill/SKILL.md`
2. Restart Claude Code
3. Type `/custom-skill` or describe your task naturally
4. Claude auto-triggers when your task matches the description

## Instructions
- Understand the user's specific context and needs
- Apply domain best practices consistently
- Provide actionable, specific guidance with examples
- Verify all outputs before presenting to user

## Gotchas
- Test with a fresh Claude instance after changes
- Keep SKILL.md under 500 lines; use references/ for details
- Description is the trigger key — make it specific and keyword-rich

🚀 怎么用

1. 复制上面的 SKILL.md 代码
2. 保存为 ~/.claude/skills/custom-skill/SKILL.md
3. 重启 Claude Code
4. 输入 /custom-skill 或直接描述任务触发
5. AI 自动按 Skill 流程执行

文件结构

每个 Skill 是一个文件夹，包含：SKILL.md（必需，核心指令+YAML元数据）、scripts/（可选，Python/Bash脚本）、references/（可选，按需读取的参考文档）、assets/（可选，输出引用的文件）。SKILL.md 是唯一必需的文件。

SKILL.md 模板

YAML 头部包含：name（小写+连字符）、description（做什么+什么时候触发，≤1024字符）、allowed-tools（最小权限原则）。正文包含：Quick Start、Common Tasks、Gotchas（踩坑清单）。目标控制在 500 行以内。

Description 是灵魂

Description 决定 Skill 会不会被触发。写得太模糊→永不触发。写得太具体→只在极窄场景触发。公式：「做什么 + 用户会说什么关键词」。用第三人称，放触发词，把即使用户没明说也该出场的场景写进去。

创建流程

1) 裸跑任务，记下你反复说什么。2) 提取可复用的模式。3) 用 skill-creator 创建最小 Skill。4) 开新 Claude 实例测试触发。5) 迭代改进：漏了什么？什么让它困惑？6) 持续从真实失败中积累 Gotchas。