技能发布者（Skill Publisher）

为技能的公开发布做好准备。在发布任何技能前，请逐项完成本清单，确保其具备可复用性、简洁性、安全性与完善的文档。

适用场景

• 向公共代码仓库推送技能前
• 向 ClawdHub 提交技能前
• 评审他人发布的技能时
• 对已发布的技能进行周期性审计时

快速检查清单

请按顺序执行以下检查项。每个部分下方均附有详细说明。

[ ] 1. STRUCTURE    - 必需文件齐全，目录结构合理
[ ] 2. SECURITY     - 不含密钥、凭据、个人身份信息（PII）或任何敏感数据  
[ ] 3. PORTABILITY  - 无硬编码路径，可在任意机器上运行
[ ] 4. QUALITY      - 代码整洁，不含调试残留内容
[ ] 5. DOCS         - README、SKILL.md 及示例完整
[ ] 6. TESTING      - 已验证技能实际可用
[ ] 7. GIT          - 提交历史干净，.gitignore 配置合理，提交信息规范
[ ] 8. METADATA     - 包含许可证、描述、关键词等元数据

1. 结构验证

必需文件

skill-name/
├── SKILL.md          # 必需 —— 入口文件，说明使用时机与快速参考
├── README.md         # 必需 —— 面向 GitHub 及人类读者
└── [content files]   # 技能的实际内容文件

SKILL.md 格式要求

必须包含以下内容：

• 标题：技能名称及一行简要描述
• 使用时机：明确触发该技能加载的具体条件
• 快速参考：最关键信息一目了然
• 详细章节：按需添加

# 技能名称

对该技能功能的一行简要描述。

## 使用时机
- 触发条件 1
- 触发条件 2

## 快速参考
[此处填写最关键的信息]

## [其他章节]
[详细内容]

文件组织原则

• 按逻辑归类相关内容
• 使用清晰、具描述性的文件名
• 保持单个文件职责单一
• 考虑加载顺序（哪些文件被优先读取？）

反模式示例

❌ 将全部内容塞入一个巨型文件
❌ 使用晦涩文件名（如 data1.md、stuff.md）
❌ 文件间存在循环依赖
❌ 缺失 SKILL.md 入口文件

2. 安全审计

密钥扫描

搜索并彻底删除以下内容：

# 在技能目录中运行
grep -rniE "(api[_-]?key|secret|password|token|bearer|auth)" . --include="*.md"
grep -rniE "([a-zA-Z0-9]{32,})" . --include="*.md"  # 可能为密钥的长字符串
grep -rniE "(sk-|pk-|xai-|ghp_|gho_)" . --include="*.md"  # 常见密钥前缀

个人信息扫描

搜索并彻底删除以下内容：

grep -rniE "(@gmail|@yahoo|@hotmail|@proton)" . --include="*.md"
grep -rniE "+?[0-9]{10,}" . --include="*.md"  # 电话号码
grep -rniE "[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}" . --include="*.md"  # IP 地址

敏感内容核查

• 不含内部公司信息
• 不含私有 URL 或接口地址
• 不含员工姓名（公众人物除外）
• 不含财务数据
• 不含任何形式的凭据
• 不含会话令牌或 Cookie

示例数据规范

若示例需使用拟真数据，请采用以下标准：

• 邮箱：user@example.com
• IP 地址：192.0.2.x（RFC 5737 文档保留地址段）
• 域名：example.com
• 人名/机构名：明显虚构名称（如 “Alice”、“Bob”、“Acme Corp”）

3. 可移植性检查

路径硬编码检查

搜索并修复以下内容：

grep -rniE "(/home/|/Users/|C:\\|~/)" . --include="*.md"
grep -rniE "/[a-z]+/[a-z]+/" . --include="*.md"  # 绝对路径

替换为：

• 相对路径（如 ./config.yaml）
• 环境变量（如 $HOME、$XDG_CONFIG_HOME）
• 跨平台通用的描述方式

环境假设检查

• 不含硬编码用户名
• 不含机器专属路径
• 不假定特定软件已安装（或需在文档中明确声明依赖）
• 不假定特定环境变量已设置（或需在文档中明确声明）
• 不使用仅限某操作系统的命令（除非提供替代方案）

依赖项文档规范

若技能依赖外部工具，请按如下格式说明：

## 要求
- `tool-name` —— [安装链接]
- 必须设置环境变量 `API_KEY`

4. 代码质量

调试残留物清理

请移除以下内容：

grep -rniE "(TODO|FIXME|XXX|HACK|DEBUG)" . --include="*.md"
grep -rniE "(console.log|print(|debugger)" . --include="*.md"

格式规范

• Markdown 风格统一
• 代码块标注语言类型（如 python、bash）
• 表格渲染正常
• 所有链接有效（无失效引用）
• 无尾部空格
• 标题层级结构一致

内容质量

• 无填充文本（如 Lorem ipsum、未完成标记）
• 无注释掉的章节
• 无重复内容
• 无过时信息
• 示例完整且可直接运行

5. 文档

README.md 检查清单

# 技能名称

简要描述（1–2 句话）。

## 包含内容
[带说明的文件列表]

## 快速概览  
[核心价值主张]

## 使用方法
[如何使用该技能]

## 要求（如有）
[依赖项、API 密钥等]

## 相关链接（如有）
[官方文档、代码仓库等]

## 许可证
[推荐技能使用 MIT 许可证]

SKILL.md 检查清单

• “使用时机”章节清晰，含具体触发条件
• 提供常见需求的快速参考
• 详细内容组织逻辑清晰
• 多文件技能需包含跨文件引用

示例要求

• 至少提供一个完整、可运行的示例
• 示例使用安全/虚构数据
• 所有示例均已测试并验证通过

6. 测试

功能测试

1. 全新加载测试：在新会话中加载技能，确认其语义清晰、行为合理
2. 触发测试：验证“使用时机”中列出的条件是否真实匹配典型用例
3. 示例测试：手动逐条执行所有示例
4. 边界测试：输入异常数据时的行为是否符合预期？

集成测试

若技能涉及调用外部工具或命令，请执行：

# 验证每个文档中提及的命令均可执行
# 确认输出结果与文档描述一致

交叉引用测试

• 所有内部链接有效
• 所有外部链接有效
• 所有文件引用准确无误

验证脚本（可选但推荐）

创建 test.sh 或记录手动测试步骤：

#!/bin/bash
# 验证技能完整性
echo "检查密钥泄露..."
grep -rniE "(api[_-]?key|secret|password)" . --include="*.md" && exit 1
echo "检查硬编码路径..."
grep -rniE "/home/" . --include="*.md" && exit 1
echo "✓ 所有检查通过"

7. Git 规范

首次提交前

创建 .gitignore 文件：

# 操作系统文件
.DS_Store
Thumbs.db

# 编辑器文件
*.swp
*.swo
*~
.idea/
.vscode/

# 临时文件
*.tmp
*.bak

# 测试产物
test-output/

提交历史规范

• 历史中从未提交过密钥（务必检查完整历史！）
• 提交粒度合理、原子化
• 提交信息含义明确

# 检查历史中是否存在密钥
git log -p | grep -iE "(api[_-]?key|secret|password|token)" 

若曾误提交密钥，请执行：

# 终极方案 —— 重写历史（请提前与协作者协调！）
git filter-branch --force --index-filter 
  'git rm --cached --ignore-unmatch path/to/sensitive/file' HEAD

提交信息格式

类型: 简短描述

- 细节 1
- 细节 2

类型包括：feat、fix、docs、refactor、test、chore

推送前检查清单

# 最终验证
git status                    # 无意外暂存内容
git log --oneline -5          # 提交信息合理
git diff origin/main          # 变更内容符合预期

8. 元数据

仓库设置

• 已填写仓库简介
• 已添加主题标签（如 claw、skill、ai-assistant）
• 已包含 LICENSE 文件

推荐许可证

对于开源技能，MIT 许可证简洁且宽松：

MIT License

Copyright (c) [年份] [作者名]

特此授予任何获得本软件及配套文档文件（“软件”）副本的人免费使用权，
允许其不受限制地使用、复制、修改、合并、发布、分发、再许可及销售软件副本，
前提是满足以下条件：

上述版权声明及本许可声明必须包含在所有软件副本或重要部分中。

本软件按“原样”提供，不附带任何明示或暗示的担保，包括但不限于适销性、
特定用途适用性及非侵权担保。在任何情况下，作者或版权持有人均不对因合同、
侵权或其他行为引起的索赔、损害赔偿或其他责任承担责任，无论是否源于本软件的
使用或与之相关。

ClawdHub 元数据（如发布至此平台）

在 SKILL.md 的 frontmatter 中声明：

---
name: skill-name
description: 一行简要描述
version: 1.0.0
author: username
tags: [tag1, tag2]
---

自动化审计脚本

每次发布前请运行此脚本：

#!/bin/bash
set -e

SKILL_DIR="${1:-.}"
cd "$SKILL_DIR"

echo "🔍 正在审计技能目录：$SKILL_DIR"
echo ""

# 1. 结构
echo "=== STRUCTURE ==="
[ -f "SKILL.md" ] && echo "✓ SKILL.md 存在" || echo "✗ SKILL.md 缺失"
[ -f "README.md" ] && echo "✓ README.md 存在" || echo "✗ README.md 缺失"
echo ""

# 2. 安全
echo "=== SECURITY ==="
if grep -rniE "(api[_-]?key|secret|password|token|bearer)=['"]?[a-zA-Z0-9]" . --include="*.md" 2>/dev/null; then
    echo "✗ 发现潜在密钥"
else
    echo "✓ 未发现明显密钥"
fi

if grep -rniE "(sk-|pk-|xai-|ghp_|gho_)[a-zA-Z0-9]" . --include="*.md" 2>/dev/null; then
    echo "✗ 发现 API 密钥特征模式"
else
    echo "✓ 未发现 API 密钥特征模式"
fi
echo ""

# 3. 可移植性
echo "=== PORTABILITY ==="
if grep -rniE "/home/[a-z]+" . --include="*.md" 2>/dev/null; then
    echo "✗ 发现硬编码 HOME 路径"
else
    echo "✓ 未发现硬编码 HOME 路径"
fi
echo ""

# 4. 质量
echo "=== QUALITY ==="
if grep -rniE "(TODO|FIXME|XXX)" . --include="*.md" 2>/dev/null; then
    echo "⚠ 发现 TODO（请人工复核）"
else
    echo "✓ 未发现 TODO"
fi
echo ""

# 5. Git
echo "=== GIT ==="
[ -f ".gitignore" ] && echo "✓ .gitignore 存在" || echo "⚠ 未找到 .gitignore"
[ -d ".git" ] && echo "✓ Git 已初始化" || echo "✗ 当前非 Git 仓库"
echo ""

echo "🏁 审计完成"

发布流程

1. 运行自动化审计脚本
2. 修复所有发现的问题
3. 手动复核上方完整检查清单
4. 使用规范提交信息完成最终提交
5. 推送至 GitHub
6. （可选）提交至 ClawdHub

README 质量

一份优秀的 README 应易于发现且对人类友好。详见 docs/readme-quality.md 获取详细指南。

快速检查项

• 首行直述功能（避免 “欢迎来到……” 类表述）
• 避免 AI 行业套话（如 comprehensive、seamless、leverage、cutting-edge）
• 聚焦具体使用场景，而非模糊宣传
• 语气自然，像真人撰写，而非新闻稿
• 标题中避免过度使用 emoji 装饰

SEO 建议

• 使用用户真实搜索的关键词短语
• 最重要信息置于首段
• 功能描述具体化（例如，不写 “强大的校验”，而写 “检查 API 密钥”）

发布后操作

• 验证 GitHub 页面渲染正确
• 测试全新克隆后能否正常工作
• 若本地使用，将技能加入 AGENTS.md 技能列表
• 如有必要，在 Discord 等渠道公告