create-skill-filelisted

# Claude Agent Skill 编写规范 > 如何创建高质量的 SKILL.md 文件 ## 目录 - [快速开始](#快速开始) - [核心原则](#核心原则) - [文件结构规范](#文件结构规范) - [命名和描述规范](#命名和描述规范) - [内容编写指南](#内容编写指南) - [质量检查清单](#质量检查清单) --- ## 快速开始 ### 3步创建 Skill **第1步: 创建目录** ```bash mkdir -p .claude/skill/your-skill-name cd .claude/skill/your-skill-name ``` **第2步: 创建 SKILL.md** ```markdown --- name: your-skill-name description: Brief description with trigger keywords and scenarios --- # Your Skill Title ## When to Use This Skill - User asks to [specific scenario] - User mentions "[keyword]" ## How It Works 1. Step 1: [Action] 2. Step 2: [Action] ## Examples **Input**: User request **Output**: Expected result ``` **第3步: 测试** - 在对话中使用 description 中的关键词触发 - 观察 Claude 是否正确执行 - 根据效果调整 --- ## 核心原则 ### 1. 保持简�� 只添加 Claude **不知道**的新知识: - ✅ 项目特定的工作流程 - ✅ 特殊的命名规范或格式要求 - ✅ 自定义工具和脚本的使用方法 - ❌ 通用编程知识 - ❌ 显而易见的步骤 **示例对比**: ```markdown # ❌ 过度详细 1. 创建 Python 文件 2. 导入必要的库 3. 定义函数 4. 编写主程序逻辑 # ✅ 简洁有效 使用 `scripts/api_client.py` 调用内部 API。 请求头必须包含 `X-Internal-Token`(从环境变量 `INTERNAL_API_KEY` 获取)。 ``` ### 2. 设定合适的自由度 | 自由度 | 适用场景 | 编写方式 | |--------|---------|---------| | **高** | 需要创造性、多种解决方案 | 提供指导原则,不限定具体步骤 | | **中** | 有推荐模式但允许变化 | 提供参数化示例和默认流程 | | **低** | 容易出错、需严格执行 | 提供详细的分步指令或脚本 | **判断标准**: - 任务是否有明确的"正确答案"? → 低自由度 - 是否需要适应不同场景? → 高自由度 - 错误的代价有多大? → 代价高则用低自由度 ### 3. 渐进式披露 将复杂内容分层组织: ``` SKILL.md (主文档, 200-500行) ├── reference.md (详细文档) ├── examples.md (完整示例) └── scripts/ (可执行脚本) ``` **规则**: - SKILL.md 超过 500行 → 拆分子文件 - 子文件超过 100行