/skill-lint

Skills 开发指南

本指南面向 Skills 开发者,提供 Skills 文档编写的完整规范和最佳实践。

1. 目录结构

基于官方 Claude Code skills(skills/pdf、skills/skill-creator)的标准格式:

skill-name/
├── SKILL.md          # 必需 (官方规范)
├── LICENSE.txt       # 可选 (官方规范)
├── references/       # 可选:参考文档,按需加载 (官方规范)
├── scripts/          # 可选:可执行代码 (扩展)
└── assets/           # 可选:输出资源文件,不加载到上下文 (扩展)

说明:

• 官方规范: SKILL.md、LICENSE.txt、references/ 是 Claude Code 官方定义的标准目录
• 扩展内容: scripts/、assets/ 是本项目的扩展约定,用于更好地组织代码和资源

目录层级规则:

• scripts/、assets/、templates/ 默认保持完全扁平，文件直接放在目录根
• references/ 默认保持扁平；对于尼斯分类、审查指南、法规合集、行业标准等体量大且内部结构稳定的资料集，可以在 references/ 下增加一层集合目录，通过集合索引按需加载，避免把几十份法源文件全部展开在根目录
• 集合目录须有稳定语义和索引入口，SKILL.md 应先指向集合索引，再说明何时下钻到具体类别、章节或条文；不得为了普通文件分类制造多层嵌套
• ❌ references/docs/api/guide.md（无必要的多层嵌套）
• ❌ assets/presets/litigation.yaml（禁止子目录）
• ❌ scripts/utils/helper.py（禁止子目录）
• ✅ references/api-guide.md（普通参考文件保持扁平）
• ✅ references/nice-classification-v13-2026/class-09.md（大型结构化资料集的一层集合目录）
• ✅ assets/litigation.yaml (完全扁平)
• ✅ scripts/helper.py (完全扁平)

注意: test/ 目录中的 DECISIONS.md、TASKS.md、CHANGELOG.md 是开发协作文件,不属于最终 skill 产品。

2. 模块化设计原则

2.1 独立功能解耦

规则: 对于独立、可复用的功能模块,应抽取成单独的脚本文件,而不是全部写在主脚本中。

为什么:

• 可复用性: 其他 skill 可以通过 AI 协调调用该功能
• 可维护性: 功能边界清晰,易于测试和调试
• 可扩展性: 独立模块可以单独升级和增强

示例 (pdf-evaluator):

pdf-evaluator/
├── SKILL.md           # 技能定义
├── evaluator.py       # 主流程:评价筛选
├── summarizer.py      # 主流程:解读生成
└── pdf_ocr.py         # 独立模块:OCR 文字提取(可复用)

判断标准:

• ✅ 该功能是否可以独立使用?
• ✅ 其他 skill 是否可能需要这个功能?
• ✅ 该功能是否有清晰的输入输出?

如果答案都是"是",则应该解耦成独立脚本。

2.2 模块间协调

模块之间不直接调用,而是通过 AI 协调:

• ✅ evaluator.py 调用 pdf_ocr.py(同一 skill 内部)
• ❌ skill-a/main.py 直接调用 skill-b/main.py(跨 skill)
• ✅ AI 先调用 skill-a,再调用 skill-b(跨 skill 协调)

3. Frontmatter 元数据

SKILL.md 必须以 YAML frontmatter 开头:

---
name: skill-name
description: 本技能应在用户需要...时使用。不要用于：...
---

字段说明:

• 必填字段: name、description
• 发布字段: version、license、author、homepage、source 属于项目或平台发布策略，不是普通 Skill 的通用必填
• 普通 Skill 缺少发布字段不应判错；若项目规则或发布平台要求，再按对应规则补充
• version 如存在，必须与 CHANGELOG.md 最新版本一致
• 不应在通用模板中硬编码个人作者、个人主页或特定仓库地址

4. description 写作规范

(1) 使用第三人称

• ❌ "Use when..." 或 "当...时使用"
• ✅ "This skill should be used when..."
• ✅ "本技能应在...时使用"

(2) 添加负向触发条件（Negative Triggers）

description 应包含何时不应使用的说明，帮助 AI 更精准地匹配技能：

# 示例：包含负向触发条件
description: |
  将法律文本转换为规范的 Markdown 格式。本技能应在用户需要处理法律条文、整理法律案例时使用。
  不要用于：代码格式化、普通文本润色、非法律类文档处理。

(3) 长度限制

• description 总长度不超过 1024 字符
• 负向触发条件应简洁，1-3 条即可

(4) 完整示例

description: |
  将法律文本转换为规范的 Markdown 格式。本技能应在用户需要处理法律条文(如民法典、刑法)、整理法律案例(如最高法典型案例)、或从粘贴文本中格式化法律文档时使用。
  不要用于：代码格式化、普通文章润色、非中文法律文档。

5. 依赖管理

(1) 依赖说明位置

依赖说明应直接写在 SKILL.md 的"依赖"章节中。

(2) SKILL.md 依赖章节格式

## 依赖

### 系统依赖

| 依赖 | 安装方式 |
|------|----------|
| 软件名 | macOS: `brew install xxx`<br>Linux: `sudo apt-get install xxx` |

### Python 包

| 包名 | 用途 | 安装命令 |
|------|------|----------|
| `package-name` | 用途说明 | `pip install package-name` |

(3) 依赖包文件(可选,扩展)

如需管理 Python 依赖,可在 scripts/ 或 assets/ 目录下使用 requirements.txt:

pip install -r scripts/requirements.txt

注意: requirements.txt 只应包含硬依赖(缺了脚本就跑不了的包)。可选依赖不应列入,而应在脚本中用 try/except 优雅降级。

(4) 脚本依赖防护

所有包含外部依赖的脚本必须做优雅降级处理:

• 硬依赖: try/except 包裹 import,捕获后输出安装提示并退出
• 可选依赖: try/except 包裹 import,设置功能标志,静默降级

# 硬依赖示例
try:
    from docx import Document
except ImportError:
    print("❌ 缺少依赖: python-docx")
    print("   请运行: pip install -r scripts/requirements.txt")
    raise SystemExit(1)

# 可选依赖示例
try:
    from PIL import Image
    HAS_PIL = True
except ImportError:
    HAS_PIL = False

(5) SKILL.md 依赖声明位置

依赖安装说明应就近放置在需要该依赖的功能章节内,而非集中在文档末尾。用户在阅读某个功能时,应该能立刻看到需要安装什么。

6. Progressive Disclosure 设计

Skills 使用渐进式加载系统管理上下文:

(1) Level 0: Frontmatter (始终加载)

• SKILL.md 的 YAML frontmatter
• 保持精简，普通 Skill 只硬性要求 name、description；version、license、author、homepage 等发布元数据按项目规则添加
• 用于技能发现和匹配,必须极度精简

(2) Level 1: 核心文档 (按需加载)

• SKILL.md 的正文内容
• 当技能被触发时才加载到上下文
• 应包含核心操作流程和常用示例
• 避免大段代码,使用简洁示例
• 通过引用指向 scripts/ 和 references/
• 行数限制: SKILL.md 正文应控制在 500 行以内，超出部分应拆分到 references/

(3) Level 2: 支持性文档 (不自动加载,官方规范)

• references/ 目录中的详细文档
• 仅在 SKILL.md 中明确引用时由 AI 主动读取
• 包含详细API文档、完整示例、边缘案例
• 目录层级: 普通参考文件保持扁平；大型结构化资料集可使用一层集合目录，并通过集合索引实施按需加载

(4) Level 3: 可执行资源 (调用不加载,扩展)

• scripts/ 目录中的可执行脚本
• assets/ 目录中的资源文件
• 通过 Bash 工具直接调用,不占用上下文
• 代码应放在这里,而非文档中

7. 文档编写最佳实践

(1) Frontmatter 优化

• description 必须精准,总长度不超过 1024 字符
• 明确触发场景,使用"本技能应在...时使用"格式
• 建议补充"不要用于..."说明技能边界
• version 如存在,必须与 CHANGELOG.md 最新版本一致
• 不要把个人默认作者、主页、许可证写进通用 Skill 模板
• 避免冗余关键词堆砌

(2) SKILL.md 内容原则

1. 避免大段代码 - 代码应放在 scripts/ 中
2. 使用简洁示例 - 仅展示关键API调用
3. 引用而非粘贴 - 指向 scripts/ 和 references/
4. 聚焦工作流程 - 说明"做什么"和"怎么做"

(3) 何时使用 scripts/ (扩展)

• 可复用的代码逻辑
• 完整的工具脚本
• 需要多次调用的函数
• 超过20行的代码

(4) 何时使用 references/ (官方规范)

• 详细的API文档
• 完整的使用案例
• 边缘场景处理
• 历史版本说明

(5) 何时使用 assets/ (扩展)

• 输出模板文件
• 配置文件示例
• 二进制资源
• requirements.txt

8. 配置文件规范

(1) 文件命名规则

示例:

.env.example            → 提交（模板）
.env                    → 忽略（实际配置）
config.yaml.example     → 提交（模板）
config.yaml             → 忽略（实际配置）

(2) 自包含项目原则

每个 skill 是自包含项目，所有配置在项目目录内管理：

• ✅ 模板文件放在 assets/ 目录
• ✅ 配置文件与模板文件在同一目录
• ✅ 用户复制 .env.example 为 .env（同目录）
• ✅ 代码从项目目录读取配置文件
• ❌ 不要要求用户复制到外部目录（如 ~/.xxx/）

(3) 配置文件格式选择

根据配置复杂度选择：

.env 代码读取：

from dotenv import load_dotenv
load_dotenv()
import os
api_key = os.getenv("GITHUB_PAT")

(4) 预设配置格式

# config.yaml.example
presets:
  quick:
    path: ./notes
    top_k: 5
  personal:
    path: ~/Documents/Obsidian
    top_k: 10
default: personal

python3 skill.py "主题" --config config.yaml --preset quick

(5) 输出路径配置

所有涉及文件输出的 Skill 都应支持可配置的输出路径。

# assets/config.yaml.example
output_dir: ""  # 为空时默认保存到 skill 内部的 output/ 目录

(6) 配置文件忽略

注意: .gitignore 在项目根目录配置，涵盖所有需要忽略的文件。

9. 技能间协作规范

(1) 核心原则

Skill 之间通过 AI 智能协调，不直接在脚本中调用其他 skill 的内部脚本。

(2) 协作文档写法

在 SKILL.md 中使用自然语言描述协作关系：

推荐写法：

## 与其他技能配合

下载的视频可以使用 FunASR 技能转录为带时间戳的 Markdown 文件。
两个技能独立运行，可根据需要灵活组合使用。

避免写法：

## 与其他技能配合

转录时运行：
\`\`\`bash
python ../../skills/local-asr/scripts/transcribe.py
\`\`\`

(3) 复杂编排

对于定时任务、条件分支、串行/并行执行等复杂编排，请参考 skill-orchestration-guide.md。

10. 安全审计

(1) 基本原则

• ❌ 不在 skill 中硬编码 API keys
• ❌ 不读取 ~/.env 或其他敏感配置
• ✅ 最小权限原则：只请求必要的工具权限
• ✅ 第三方依赖使用官方库
• ❌ 禁止使用 rm -rf ~、rm -rf /、rm -rf $HOME 等危险命令
• ✅ 使用 trash 或安全删除脚本替代 rm -rf

(2) 安全删除规范

禁止：rm -rf ~、rm -rf /、rm -rf $HOME 等危险命令

推荐：

# 使用 trash 命令（移动到回收站）
trash ./output

# 清理目录内容（保留目录本身）
find ./output -mindepth 1 -delete

(3) 审计检查清单

开发时确保：

• 无硬编码的敏感信息
• 无未授权的文件访问
• 最小工具权限
• 依赖来自可信源
• 无 rm -rf ~、rm -rf / 等危险命令
• Makefile/shell 脚本中的删除命令经过审查

11. 开发流程

(1) 创建新 Skill

1. 先调用 skill-lint 的创建预检，定义 Contract / Producer / Verifier / Evidence Binding / Fault Injection / Closure / Composition 七层设计、Hard Fail 和至少一个逃逸反例。
2. 再由 Skill 创建工具或实现者在 skills/ 目录下创建 SKILL.md 和必要的 references/、scripts/、assets/。如需配置文件，使用不含真实值的 example。
3. 实现完成后回到 skill-lint 做正式验收；创建者不能用自报 PASS 代替独立 checker。

(2) 开发时优先事项

1. 通用性优先

   • 不假设特定用户/目录/配置
   • 使用配置文件适配不同场景
   • 支持命令行参数覆盖配置

2. 自包含

   • 所有依赖明确列出
   • 路径使用相对路径或配置
   • 无外部硬依赖

3. 可测试

   • 提供 --max-items 等测试参数
   • 支持小范围数据验证

12. 技能验证规范

完成技能开发后，应进行以下验证测试：

(1) 发现验证 (Discovery Validation)

验证 AI 能否正确识别技能触发条件：

• 正向测试：给定相关用户请求，验证技能是否被正确触发
• 负向测试：给定不相关请求，验证技能不会被误触发

(2) 逻辑验证 (Logic Validation)

验证技能的核心逻辑是否正确：

• 核心流程测试：执行技能的主要功能
• 边缘案例测试：处理异常输入、空值、边界条件

(3) Skill Lint 分阶段验收

使用 skill-lint 验证技能是否符合规范和 Harness 可靠性：

• 目录结构合规
• Frontmatter 格式正确
• description 包含负向触发条件
• SKILL.md 行数在 500 行以内
• references/ 普通文件扁平；大型结构化资料集使用一层集合目录时具备索引入口
• 创建或重大改造前已完成七层 Harness 预检
• 正式验收由门禁实时重跑候选内 checker 与故障用例
• 动态运行仅限用户确认的自有/可信候选；未知第三方候选在隔离环境外保持 NOT_VERIFIED
• 报告区分 HARNESS_REVIEW_VERIFIED、DOMAIN_VERIFIED 和 NOT_VERIFIED

13. skill-dev-guide.md 更新规范

重要: 本指南文件(skill-dev-guide.md)的每次修改都必须同步更新底部的"变更历史"章节。

(1) 更新流程

1. 修改内容: 在 skill-dev-guide.md 中进行任何修改(新增/修改规范、调整格式等)
2. 更新变更历史: 在"变更历史"表格顶部添加新的版本记录
3. 版本号递增: 根据修改性质递增版本号

(2) 版本号规则

• 小修改(格式调整、文字优化): 递增最后一位(如 v1.0.1 → v1.0.2)
• 新增规范: 递增中间一位(如 v1.0.1 → v1.1.0)
• 重大变更: 递增第一位(如 v1.0.1 → v2.0.0)

(3) 变更历史记录格式

(4) 自动更新要求

AI 代理在修改 skill-dev-guide.md 时,必须:

1. 检查是否对文件内容进行了实质性修改
2. 如果是,自动在"变更历史"表格顶部添加新记录
3. 递增版本号

变更历史