如何编写你自己的Claude-Skill：从SKILL.md到Python工具的完整教程

Claude-Skills 是一个开源 AI 技能库，收录了 385 个 skills、77 个 expert agents 和数百个 stdlib Python 工具，支持 Claude Code、Cursor、Codex、Gemini 等 11 个 AI 助手。本教程将带你从零开始编写并校验一个符合标准的 Claude Skill：先了解 Skill 的标准目录结构，再用脚手架一键生成骨架，接着动手编写 SKILL.md 与 Python 工具脚本，最后用内置的 skill-tester 完成质量评分。全程只需用到 Python 标准库，无需任何额外依赖。

一、Claude Skill 的标准目录结构

每个 Skill 都是一个自包含的文件夹，用户拷走即可直接使用。标准布局如下：

skill-name/ ├── SKILL.md # 主文档（必需，AI 助手的入口） ├── scripts/ # Python CLI 工具（推荐） │ └── tool.py ├── references/ # 深度知识库（可选，给 AI 的上下文） │ └── guide.md └── assets/ # 用户可复用的模板（可选） └── template.md

知识流动方向是：references/提供领域知识 → 驱动SKILL.md中的工作流 → 通过scripts/工具执行 → 产出使用assets/模板。完整架构说明见 site/assets/images/social/reference/architecture.png 对应的文档页 docs/reference/architecture.md，目录结构规范在 standards/skill-authoring-standard.md 中有逐条定义。

三条硬性规则（新手最容易踩坑）：

• SKILL.md控制在 500 行以内，超出部分拆进references/
• 脚本只允许 Python 标准库，禁止pip install第三方包和 LLM/ML 调用
• 禁止跨 Skill 引用文件，把公共函数复制一份到自己目录里

二、用 create_skill.py 一键生成骨架

不要手写目录结构——项目自带脚手架脚本 scripts/create_skill.py，它会创建目录并预填好符合规范的 SKILL.md 模板：

# 克隆仓库（如需本地开发） git clone https://gitcode.com/gh_mirrors/claudesk/Claude-Skills cd Claude-Skills # 生成骨架：路径必须是「域名/技能名」 python scripts/create_skill.py engineering/my-new-skill --author your-name --tags "devops,tools"

生成的骨架包含SKILL.md和scripts/、references/、examples/三个子目录，SKILL.md 中已预填 frontmatter 模板和 Quick Start、Anti-Patterns 等章节占位符。加--dry-run可以先预览而不写文件。支持的 12 个域包括engineering、marketing、project-management等，完整清单见 CONTRIBUTING.md。

三、SKILL.md：写好 frontmatter 与触发描述

SKILL.md 是整个 Skill 的心脏。AI 助手靠扫描description字段来决定是否激活你的技能，因此官方标准（Pattern 1）要求采用"做什么 + 何时用"两段式写法：

--- name: my-skill-name # 小写连字符，必须与文件夹同名 description: > 一句话说明功能。Use when 触发场景A, 触发场景B, 触发场景C. license: MIT metadata: version: 1.0.0 author: your-name category: engineering # 必须匹配顶层目录名 domain: my-subdomain updated: 2026-10-23 tags: [tools, automation] ---

frontmatter 字段规则（完整表格见 standards/skill-authoring-standard.md）：

正文至少包含四部分：When to Use（触发条件）、Workflows（分步工作流）、Best Practices（领域专家建议）、Tool Reference（每个脚本的运行方法）。一个可直接模仿的完整样例是 engineering/skill-tester/assets/sample-skill/SKILL.md，写法指南原文在 docs/guides/authoring.md。

💡 官方反例对比：写"This skill helps with architecture"等于什么都没说；应写成"System design for production software. Activate when designing new systems, evaluating tradeoffs, planning migrations"。

四、Python 工具脚本编写规范

scripts/下的每个脚本都是独立的 CLI 工具，遵循统一骨架（详见 docs/guides/authoring.md）：

#!/usr/bin/env python3 """Tool description — what it does and what it outputs.""" import argparse import json import sys def main() -> None: parser = argparse.ArgumentParser(description="Tool description") parser.add_argument("input", help="Input file or directory") parser.add_argument("--format", choices=["json", "text"], default="text") args = parser.parse_args() # 分析逻辑，支持 JSON 与人类可读双输出 # 成功 exit 0，失败 exit 非零

关键约束一览：

• 标准库 only：argparse、json、pathlib、typing，绝不依赖 pip 包
• 双输出：同时支持--format json（供 CI 消费）和人类可读格式
• 150–300 行：太少说明功能缺失，太多说明该拆分成多个脚本
• 必须带--help、类型标注、docstring，所有异常要有可操作的错误提示
• 禁止调用 LLM/ML 接口——保持确定性与速度

参考实现可打开 engineering/skill-tester/scripts/skill_validator.py 学习真实项目中的写法。

五、可选增强：references 与 assets

• references/：存放深度知识库（框架、检查清单、监管条文），单文件上限 800 行。SKILL.md 中用相对路径链接即可，如 engineering/skill-tester/SKILL.md 对 5 份 references 的引用方式。
• assets/：用户拿来即改的交付物模板，如报告模板、示例数据，无行数限制。
• 如果你的技能会生成交付物，建议加一个Clarify First小节：列出 2–4 个最影响输出的输入项，未知时先问用户而不是擅自假设。

六、用 skill-tester 校验与评分

提交前务必跑一遍官方校验器 engineering/skill-tester/，三个工具各司其职：

# 1. 校验目录结构、frontmatter、必需章节 python engineering/skill-tester/scripts/skill_validator.py path/to/your-skill --tier POWERFUL --json # 2. 语法 + stdlib 导入检查 + 实际运行 --help python engineering/skill-tester/scripts/script_tester.py path/to/your-skill --timeout 30 # 3. 四维度质量打分（A+ 到 F）并给出改进路线图 python engineering/skill-tester/scripts/quality_scorer.py path/to/your-skill --detailed --minimum-score 75

校验器会检查 YAML 完整性、脚本是否纯标准库、是否支持--format json，并按 BASIC / STANDARD / POWERFUL 三级给出结构阈值。

七、发布前质量清单

对照 standards/skill-authoring-standard.md 的最终 Checklist 自查：

• ✅name与目录名一致，frontmatter 字段齐全
• ✅ SKILL.md ≤ 500 行，前 3 行就能让 AI 判断何时激活
• ✅ 建议有立场——"Use X because Y" 优于 "You could use X or Y"
• ✅ 至少 3 条来自真实经验的 Anti-Patterns
• ✅ 脚本全部通过 stdlib-only 检查，双格式输出
• ✅把整个 Skill 文件夹复制到空目录，确认所有相对路径可解析（自包含测试）
• ✅ 能帮用户节省 40% 以上时间——达不到就重新设计

完成以上步骤，你的第一个 Claude Skill 就正式可用了。想进一步把它包装成专家角色，可参考 templates/agent-template.md 中的 agent 模板。祝创作顺利 🚀