鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

create-skill-file

指导 Claude 创建结构清晰、易于发现和执行的 SKILL.md 文件,涵盖命名规范、文件组织、内容编写及质量检查全流程,强调简洁性、场景化触发和渐进式信息呈现。

文档处理数据与分析商业与营销
访问 GitHub
文档Skills.MD
name
create-skill-file
description
Guides Claude in creating well-structured SKILL.md files following best practices. Provides clear guidelines for naming, structure, and content organization to make skills easy to discover and execute.

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. 渐进式披露

将复杂内容分层组织:

▼
text
复制代码
SKILL.md (主文档, 200-500行) ├── reference.md (详细文档) ├── examples.md (完整示例) └── scripts/ (可执行脚本)

规则:

  • SKILL.md 超过 500行 → 拆分子文件
  • 子文件超过 100行 → 添加目录
  • 引用深度 ≤ 1层

文件结构规范

YAML Frontmatter

▼
yaml
复制代码
--- name: skill-name-here description: Clear description of what this skill does and when to activate it ---

字段规范:

字段要求说明
name小写字母、数字、短横线,≤64字符必须与目录名一致
description纯文本,≤1024字符用于检索和激活

命名禁忌:

  • ❌ XML 标签、保留字(anthropic, claude)
  • ❌ 模糊词汇(helper, utility, manager)
  • ❌ 空格或下划线(用短横线 -)

Description 技巧:

▼
yaml
复制代码
# ❌ 过于泛化 description: Helps with code tasks # ✅ 具体且包含关键词 description: Processes CSV files and generates Excel reports with charts. Use when user asks to convert data formats or create visual reports. # ✅ 说明触发场景 description: Analyzes Python code for security vulnerabilities using bandit. Activates when user mentions "security audit" or "vulnerability scan".

目录组织

基础结构(简单 Skill):

▼
text
复制代码
skill-name/ └── SKILL.md

标准结构(推荐):

▼
text
复制代码
skill-name/ ├── SKILL.md ├── templates/ │ └── template.md └── scripts/ └── script.py

命名和描述规范

Skill 命名

推荐格式: 动名词形式 (verb-ing + noun)

▼
text
复制代码
✅ 好的命名: - processing-csv-files - generating-api-docs - managing-database-migrations ❌ 不好的命名: - csv (过于简短) - data_processor (使用下划线) - helper (过于模糊)

Description 编写

必须使用第三人称:

▼
yaml
复制代码
# ❌ 错误 description: I help you process PDFs # ✅ 正确 description: Processes PDF documents and extracts structured data

4C 原则:

  • Clear (清晰): 避免术语和模糊词汇
  • Concise (简洁): 1-2句话说明核心功能
  • Contextual (上下文): 说明适用场景
  • Complete (完整): 功能 + 触发条件

内容编写指南

"When to Use" 章节

明确说明触发场景:

▼
markdown
复制代码
## When to Use This Skill - User asks to analyze Python code for type errors - User mentions "mypy" or "type checking" - User is working in a Python project with type hints - User needs to add type annotations

模式:

  • 直接请求: "User asks to X"
  • 关键词: "User mentions 'keyword'"
  • 上下文: "User is working with X"
  • 任务类型: "User needs to X"

工作流设计

简单线性流程:

▼
markdown
复制代码
## How It Works 1. Scan the project for all `.py` files 2. Run `mypy --strict` on each file 3. Parse error output and categorize by severity 4. Generate summary report with fix suggestions

条件分支流程:

▼
markdown
复制代码
## Workflow 1. **Check project type** - If Django → Use `django-stubs` config - If Flask → Use `flask-stubs` config - Otherwise → Use default mypy config 2. **Run type checking** - If errors found → Proceed to step 3 - If no errors → Report success and exit

Checklist 模式(验证型任务):

▼
markdown
复制代码
## Pre-deployment Checklist Execute in order. Stop if any step fails. - [ ] Run tests: `npm test` (must pass) - [ ] Build: `npm run build` (no errors) - [ ] Check deps: `npm audit` (no critical vulnerabilities)

示例和模板

输入-输出示例:

▼
markdown
复制代码
## Examples ### Example 1: Basic Check **User Request**: "Check my code for type errors" **Action**: 1. Scan for `.py` files 2. Run `mypy` on all files **Output**: Found 3 type errors in 2 files: src/main.py:15: error: Missing return type src/utils.py:42: error: Incompatible types

脚本集成

何时使用脚本:

  • 简单命令 → 直接在 SKILL.md 中说明
  • 复杂流程 → 提供独立脚本

脚本编写规范:

▼
python
复制代码
#!/usr/bin/env python3 """ Brief description of what this script does. Usage: python script.py <arg> [--option value] """ import argparse DEFAULT_VALUE = 80 # Use constants, not magic numbers def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("directory", help="Directory to process") parser.add_argument("--threshold", type=int, default=DEFAULT_VALUE) args = parser.parse_args() # Validate inputs if not Path(args.directory).is_dir(): print(f"Error: {args.directory} not found") return 1 # Execute result = process(args.directory, args.threshold) # Report print(f"Processed {result['count']} files") return 0 if __name__ == "__main__": exit(main())

关键规范:

  • ✅ Shebang 行和 docstring
  • ✅ 类型注解和常量
  • ✅ 参数验证和错误处理
  • ✅ 清晰的返回值(0=成功, 1=失败)

最佳实践

Do:

  • ✅ 提供可执行的命令和脚本
  • ✅ 包含输入-输出示例
  • ✅ 说明验证标准和成功条件
  • ✅ 包含 Do/Don't 清单

Don't:

  • ❌ 包含 Claude 已知的通用知识
  • ❌ 使用抽象描述而非具体步骤
  • ❌ 遗漏错误处理指导
  • ❌ 示例使用伪代码而非真实代码

质量检查清单

核心质量

  • name 符合命名规范(小写、短横线、≤64字符)
  • description 包含触发关键词和场景(≤1024字符)
  • 名称与目录名一致
  • 只包含 Claude 不知道的信息
  • 没有冗余或重复内容

功能完整性

  • 有"When to Use"章节,列出 3-5 个触发场景
  • 有清晰的执行流程或步骤
  • 至少 2-3 个完整示例
  • 包含输入和预期输出
  • 错误处理有指导

结构规范

  • 章节组织清晰
  • 超过 200行有目录导航
  • 引用层级 ≤ 1层
  • 所有路径使用正斜杠 /
  • 术语使用一致

脚本和模板

  • 脚本包含使用说明和参数文档
  • 脚本有错误处理
  • 避免魔法数字,使用配置
  • 模板格式清晰易用

最终检查

  • 通读全文,确保流畅易读
  • 使用实际场景测试触发
  • 长度适中(200-500行,或已拆分)

常见问题

Q: Skill 多长才合适?

  • 最小: 50-100行
  • 理想: 200-500行
  • 最大: 500行(超过则拆分)

Q: 如何让 Skill 更容易激活?

  • 在 description 中使用用户会说的关键词
  • 说明具体场景("when user asks to X")
  • 提及相关工具名称

Q: 多个 Skill 功能重叠怎么办?

  • 使用更具体的 description 区分
  • 在"When to Use"中说明关系
  • 考虑合并为一个 Skill

Q: Skill 需要维护吗?

  • 每季度审查一次,更新过时信息
  • 根据使用反馈迭代
  • 工具或 API 变更时及时更新

快速参考

Frontmatter 模板

▼
yaml
复制代码
--- name: skill-name description: Brief description with trigger keywords ---

基础结构模板

▼
markdown
复制代码
# Skill Title ## When to Use This Skill - Scenario 1 - Scenario 2 ## How It Works 1. Step 1 2. Step 2 ## Examples ### Example 1 ... ## References - [Link](url)

相关资源

  • Claude Agent Skills 官方文档
  • Best Practices Checklist
  • 模板文件 - 开箱即用的模板
    • 基础 skill 的模板
    • 工作流 skill 的模板
  • 示例库 - 完整的 Skill 示例
    • 优秀示例
    • 常见错误示例

文档处理
数据与分析
商业与营销

快捷安装

复制到终端去安装 Skill

npxadd-skilllabring/FastGPT--skill"create-skill-file"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
definition-of-done-generator
自动生成项目完成标准的规范定义与配置文件,提供符合企业级工作流要求的最佳实践指导,输出可直接投入生产环境的代码和验证结果,适用于需要标准化流程审批、合规审查及跨系统集成的复杂项目管理场景。
skill-planner
将研究结论转化为结构化、分阶段的落地执行方案,涵盖范围界定、任务拆解、风险预判与验证标准,确保每阶段目标明确、可独立验证,并自动生成符合规范格式的实施计划文档。
planning-with-files
通过创建任务计划、笔记与交付文件三个持久化文档,实现对复杂任务的结构化管理。在多阶段工作中保持目标清晰,动态更新进度并沉淀研究过程,适用于需长期跟踪的规划、研究及创作场景。
sagemaker-endpoint-deployer
自动化部署机器学习模型至云端服务端点,支持从配置生成到生产验证的全流程,适用于模型上线、服务监控与推理优化等场景,确保部署方案符合工业级标准。
docx
支持专业级 Word 文档的全生命周期处理,包括从零创建结构化文档、精准编辑内容、管理修订痕迹与批注、提取纯文本或原始 XML 数据、转换为 PDF 或图像用于视觉分析,适用于法律、学术及企业场景下的高保真文档协作与自动化处理。