dcjanus/create-skill

Create Skill（本仓库约定）

1) 目录结构与命名

每个 skill 一个目录，目录名与 frontmatter 的 name 完全一致：

• name 约束：
  • 仅允许小写字母/数字/连字符：a-z、0-9、-
  • 不能以 - 开头或结尾
  • 不能包含连续 --

推荐结构：

skills/<skill-name>/
  SKILL.md
  scripts/        # 可选：可执行工具
  references/     # 可选：按需阅读的资料
  assets/         # 可选：模板/静态文件

2) SKILL.md（必需）

2.1 Frontmatter（必需：name / description）

---
name: your-skill-name
description: 用一句话说明“做什么 + 何时使用（包含关键词）”。
---

可按需添加其他字段；本仓库不强制要求，但建议保持精简。

description 要求：

• 非空
• 必须同时覆盖“做什么”+“何时使用”
• 尽量包含用户会说出口的关键词（提升触发命中率）

2.2 正文（只写最短可用流程）

正文只保留“让使用者（人或 AI）直接开始执行”的信息。大段背景/资料放到 references/，模板/静态文件放到 assets/。

推荐顺序（按需取舍）：

1. 一句话说明（这是什么/解决什么）
2. Quick start（最短可复制示例）
3. 常用场景/命令（3-7 条为宜）
4. 输出约定（如机器可读输出，明确 --json 等约定）
5. 冷门参数怎么查（--help + reference 指针）
6. 资源（指向脚本/参考资料/模板）

最小骨架（可复制改名）：

---
name: your-skill-name
description: 做什么；何时使用（关键词）。
---

一句话说明。

## Quick start

```bash
cd skills/your-skill-name && ./scripts/your_tool.py --help
```

## 常用场景
- `./scripts/your_tool.py ...`

## 冷门参数怎么查
- `./scripts/your_tool.py --help`
- 需要字段细节时读：见 [api.md](references/api.md)

## 资源
- [tool.py](scripts/tool.py)

3) scripts/（可选）

如果某个流程需要“确定性执行”或经常重复，优先写成可执行脚本放在 scripts/，并在 SKILL.md 中给出可复制命令。

本仓库对 Python 脚本的约定（SKILL.md 里要写清楚）：

• 统一通过 ./scripts/... 直接执行（不要用 uv run python ... / python ...）
• workdir 约定：默认以当前 SKILL.md 所在目录作为 workdir；示例命令如需 cd，应写清楚（通常 cd skills/<skill-name>）
• 在 SKILL.md 中引用脚本/资源文件时，优先使用 Markdown URL（链接文本尽量只写文件名）

Python 脚本规范要点：

• 运行模式：必须使用 uv script 模式（shebang 为 #!/usr/bin/env -S uv run --script）。
• 适用范围：以上 uv script 约定仅适用于“直接执行的入口脚本”（通常位于 scripts/ 且会通过 ./scripts/... 运行）。被入口脚本 import 的普通 Python 模块不要添加 shebang 或 /// script 元数据块，依赖统一声明在入口脚本头部。
• 初始化：新建脚本用 uv init --script scripts/foo.py（生成 shebang 与空的 /// script 元数据块）。
• 依赖声明（强约束）：
  • 脚本头部 /// script 元数据块是唯一依赖声明位置。
  • 禁止手工编辑依赖块；依赖增删必须通过 uv add --script ... / uv remove --script ... 完成。
  • 移除依赖引用后，若确认不再使用，应同步移除该依赖。
• CLI 形态：
  • 命令行参数优先用 Typer。
  • 对离散可选值（如 format、view、profile、column 等），优先使用 Enum 或 Literal 做类型标注，而不是只靠 help 文案描述可选值；这样 Typer 可以自动在 --help 中展示候选值，提升可读性与可发现性。
  • 取舍建议：少量、一次性使用的枚举值可优先用 Literal；需要复用、集中管理或值较多时优先用 Enum。
  • 输出提示/表格优先用 rich（提升可读性）。
  • 数据模型与参数校验优先用 pydantic（失败信息清晰可定位）。
  • Typer 应用实例变量名使用小写 app。
  • 若仅一个 command，优先使用 typer.run(main)，避免 tool.py foo <arg> 这种多一层子命令。
• 可维护性：每个模块、函数与类型都应包含简短中文 docstring。
• 质量检查：完成后建议执行：
  • uv run ruff check <path>
  • uv run ruff format <path>

常用 uv --script 工作流（用于新建/维护脚本依赖）：

# 在 skill 目录内新建脚本（会生成 shebang 与 /// script 依赖块）
uv init --script scripts/foo.py

# 给脚本添加依赖（会更新脚本头部 dependencies；不要手工改依赖块）
uv add --script scripts/foo.py typer rich

# 从脚本移除依赖
uv remove --script scripts/foo.py rich

# 赋予可执行权限并运行
chmod +x scripts/foo.py
./scripts/foo.py --help

4) references/ 与 assets/（可选）

• references/：放“按需阅读”的长资料（协议/API 字段/术语表）。在 SKILL.md 中写清楚“什么时候需要读哪个文件”。
• assets/：放模板/静态文件。在 SKILL.md 中给出“如何使用该文件”的最短说明。

引用规则（建议）：

• 链接或路径使用相对路径（相对 skills/<skill-name>/）
• 尽量“一跳可达”：SKILL.md 直接指向目标文件，避免多层链式引用
• 链接文本尽量只写文件名（路径放在链接目标里）

示例（Markdown 链接语法）：

见 [api.md](references/api.md)
运行 [tool.py](scripts/tool.py)

5) 内容长度（token）

• SKILL.md 正文推荐 < 5000 tokens
• 可用 token_count.py 统计 token 数（脚本与参数不依赖 workdir，只要路径写对即可）：

cd skills/<skill-name>
../../scripts/token_count.py SKILL.md

6) 提交前自检清单

• 目录名 == SKILL.md 的 name
• frontmatter 至少包含 name / description，且 description 写清楚 “做什么 + 何时用（关键词）”
• SKILL.md 有可复制的 Quick start（如依赖工作目录或环境变量，需要在示例中写清楚）
• 如有脚本：示例使用 ./scripts/... 直接执行（不使用 uv run python/python）
• 如有脚本：依赖只在 /// script 里声明（不手改依赖块）；模块/函数/类型有简短中文 docstring
• 如有脚本：建议跑 ruff（uv run ruff check ... / uv run ruff format ...）
• references//assets/ 的引用清晰，且 SKILL.md 能一跳到达目标文件
• SKILL.md token 数在建议范围内