create-seed-skill

创建 Seed Skill

从零开始搭建一个集成类 Skill。Seed Skill 由 SKILL.md、参考资源和 prompts.jsonl 条目组成，这些内容共同指导 Agent 构建出可运行、可测试的集成。

何时使用

集成类 Skill（使用此 Skill）：

• 使用代码生成和真实 API 测试封装 SDK 或框架
• 评估问题是：“Agent 是否编写了调用真实 API 并通过测试的代码？”
• 示例：ydc-ai-sdk-integration、teams-anthropic-integration

工具类 Skill（不要使用此 Skill）：

• CLI 封装：Agent 运行命令，而不是编写代码
• 没有测试目录，也没有生成的文件
• 示例：youdotcom-cli

决策点

先询问开发者：

这是集成类 Skill（Agent 生成代码和测试），还是工具类 Skill（Agent 运行 CLI 命令）？

• 集成类 → 继续此工作流
• 工具类 → 停止。工具类 Skill 不需要此 Skill。

---

工作流

第 1 步 — 收集信息

一次性询问以下所有问题（不要逐个询问）：

1. Skill 名称：应该叫什么？（小写，使用连字符，例如 my-sdk-integration）
2. 包：它封装了哪些 npm/pip 包？请提供准确的包名称。
3. 语言：TypeScript、Python，还是两者？
   • 两者表示：每种语言使用单独的资源文件、添加两个 prompts.jsonl 条目（一个 -typescript，一个 -python），并创建两个 tests/ 目录（tests/<skill-name>-typescript/ 和 tests/<skill-name>-python/），每个目录都包含一个 .gitkeep 文件。
   • 一种语言表示：一套资源、一个 prompts.jsonl 条目，以及一个包含 .gitkeep 文件的 tests/<skill-name>/ 目录。
4. 路径 A（基础）：最简单可行的集成是什么——一个函数、一次 API 调用？
5. 路径 B（扩展）：自然的扩展方向是什么——MCP、流式传输、工具筛选等？
6. 必需的环境变量：需要哪些 API 密钥？（例如 MY_API_KEY、OPENAI_API_KEY）
7. 测试查询：集成应能回答什么事实性问题，且答案应包含确定的多个关键词？（参见选择测试查询）

第 2 步 — 阅读参考资源

编写任何代码之前，请先阅读参考资源，了解所需的结构：

• assets/example-SKILL.md — 完整的 SKILL.md 模板
• assets/example-path-a.ts — TypeScript 路径 A 资源结构
• assets/example-test.spec.ts — TypeScript 测试资源结构
• assets/example-pyproject.toml — Python 项目配置资源
• assets/example-test_integration.py — Python 测试资源结构

第 3 步 — 创建文件

一次性创建所有文件。Skill 位于 skills/<skill-name>/。

目录布局：

skills/<skill-name>/
├── SKILL.md
└── assets/
    # TypeScript:
    ├── path-a-<variant>.ts       # Path A integration
    ├── path-b-<variant>.ts       # Path B integration (if applicable)
    ├── integration.spec.ts       # Bun test file
    # Python:
    ├── path_a_<variant>.py       # Path A integration
    ├── path_b_<variant>.py       # Path B integration (if applicable)
    ├── test_integration.py       # pytest file
    └── pyproject.toml            # Python project config (required for uv run pytest)

# Also create (see below):
tests/<skill-name>/               # single language
└── .gitkeep
# — or for both languages —
tests/<skill-name>-typescript/
└── .gitkeep
tests/<skill-name>-python/
└── .gitkeep

还要创建 tests/ 评估目标目录（或多个目录），并添加 .gitkeep 文件，以便在 Agent 写入文件前，该目录已存在于 Git 中：

• 一种语言：tests/<skill-name>/.gitkeep
• 两种语言：tests/<skill-name>-typescript/.gitkeep 和 tests/<skill-name>-python/.gitkeep

# Single language (adjust path as needed):
mkdir -p tests/<skill-name> && touch tests/<skill-name>/.gitkeep

# Both languages:
mkdir -p tests/<skill-name>-typescript tests/<skill-name>-python
touch tests/<skill-name>-typescript/.gitkeep tests/<skill-name>-python/.gitkeep

第 4 步 — 添加 prompts.jsonl 条目

在 data/prompts/prompts.jsonl 中为每种语言追加一个条目。

单一语言模板（选择一个具体示例——不要将 TypeScript 或 Python 留作占位符）：

TypeScript：

{"id":"<skill-name>","input":["Using the <skill-name> skill, create a working TypeScript <description of Path A> integration. Write flat minimal code with no comments or TSDoc. Write integration tests that call real APIs and assert on meaningful response content. Save everything to the tests/<skill-name> directory.","Extend the integration with <description of Path B>. Write flat minimal code with no comments or TSDoc. Update the integration tests to verify the extended integration also works with a live query."],"metadata":{"cwd":"tests/<skill-name>","language":"typescript"}}

Python：

{"id":"<skill-name>","input":["Using the <skill-name> skill, create a working Python <description of Path A> integration. Write flat minimal code with no comments or docstrings. Write integration tests that call real APIs and assert on meaningful response content. Save everything to the tests/<skill-name> directory.","Extend the integration with <description of Path B>. Write flat minimal code with no comments or docstrings. Update the integration tests to verify the extended integration also works with a live query."],"metadata":{"cwd":"tests/<skill-name>","language":"python"}}

两种语言 — 追加两个条目：

{"id":"<skill-name>-typescript","input":["Using the <skill-name> skill, create a working TypeScript <description of Path A> integration. Write flat minimal code with no comments or TSDoc. Write integration tests that call real APIs and assert on meaningful response content. Save everything to the tests/<skill-name>-typescript directory.","Extend the integration with <description of Path B>. Write flat minimal code with no comments or TSDoc. Update the integration tests to verify the extended integration also works with a live query."],"metadata":{"cwd":"tests/<skill-name>-typescript","language":"typescript"}}
{"id":"<skill-name>-python","input":["Using the <skill-name> skill, create a working Python <description of Path A> integration. Write flat minimal code with no comments or docstrings. Write integration tests that call real APIs and assert on meaningful response content. Save everything to the tests/<skill-name>-python directory.","Extend the integration with <description of Path B>. Write flat minimal code with no comments or docstrings. Update the integration tests to verify the extended integration also works with a live query."],"metadata":{"cwd":"tests/<skill-name>-python","language":"python"}}

prompts 规则：

• 每个条目恰好包含 2 轮
• 在第 1 轮中明确写出语言名称（“TypeScript”或“Python”），以免 Agent 猜测
• 只描述结果——绝不提及类名、方法名或配置键
• 第 1 轮：基础集成 + 测试
• 第 2 轮：扩展 + 更新测试
• metadata.cwd 必须与第 3 步创建的 tests/ 目录一致（评分器会从此处读取文件）
• metadata.language 必须是 typescript 或 python

步骤 5 — 创建符号链接

ln -s ../../skills/<skill-name> .claude/skills/<skill-name>

步骤 6 — 验证

bunx @plaited/development-skills validate-skill skills/<skill-name>

---

优质种子 Skill 的特点

SKILL.md 必须包含

1. 正确的 frontmatter — name、description、license、compatibility、allowed-tools、assets 列表、metadata
2. 决策点 — 简要说明路径 A 与路径 B，并提出一个明确的问题
3. 安装说明 — 准确的软件包名称和安装命令
4. 完整的代码模板 — 完整可运行的示例，不是伪代码
5. 安全部分 — 如果集成会获取不可信的网页内容，请包含提示词注入警告（W011）
6. 生成集成测试部分 — 指向所有资源文件的 Markdown 链接，以及明确的规则

生成集成测试规则（全部包含）

**Rules:**
- No mocks — call real APIs
- Assert on keywords from a deterministic query, not just `length > 0`
- Validate required env vars at test start (inside the test function, not at module scope)
- TypeScript: use `bun:test`, dynamic imports inside tests, `timeout: 60_000`
- Python: use `pytest`, import inside test function; always include `pyproject.toml` with `pytest` in `[dependency-groups] dev`
- Run TypeScript tests: `bun test` | Run Python tests: `uv run pytest`

参考资源必须

• 能够编译和运行 — 不得包含伪代码或占位符
• 在 Agent 的 instructions/system_prompt 中包含安全说明
• 在集成文件（作为 __main__ 示例）和测试断言中使用步骤 1 中的测试查询
• 断言关键词 — 不能只断言 length > 0
• TypeScript：导出可调用函数，并在测试中使用动态 import()
• Python：定义 main(query: str) -> str 函数，并在测试函数中使用延迟导入

---

选择测试查询

真正的目标：验证集成代码确实运行了，而不是验证 LLM 是否知道答案。

大多数 LLM 无需调用任何工具，就能凭记忆回答事实性问题。模型无需搜索就能回答的查询，并不能证明 MCP 服务或 SDK 工具已被调用——集成可能会静默跳过工具调用，但测试仍然通过。

**真正重要的是：**只有当代码路径正常运行时，测试才会通过——SDK 已初始化、MCP 服务已连通，并且已返回响应。与完全没有断言相比，能匹配典型工具输出的关键词断言更好，但它无法证明工具确实被调用。

实用建议：

• 在查询前加上明确指示，要求使用该工具 — 这样可以强制调用工具，而不是依赖模型自行判断
• 使用答案稳定且包含多个关键词的查询，以便断言内容，而不只是 length > 0
• LLM-as-judge 评分器（scripts/grader.ts）也会评估生成代码的结构，而不只是检查是否出现关键词

优秀示例（明确要求使用工具 + 关键词稳定）：

• "Search the web for the three branches of the US government" → 断言 legislative、executive、judicial
• "Use web search to find what programming language TypeScript compiles to" → 断言 javascript
• "Search the web for the four classical elements" → 断言 earth、water、fire、air

"Search the web for..." 或 "Use [tool name] to find..." 这样的前缀会将工具使用明确写成指令，而不是让模型自行推断——模型必须调用工具才能遵循提示词。

应避免：

• 纯事实性查询（“What are the three branches...”）——模型可能凭记忆回答，完全跳过工具调用
• “What is the latest news in AI?”——内容每天都在变化，没有可预测的关键词
• “Say hello in one sentence.”——无法对有意义的内容进行断言

评测评分器说明

评分器（scripts/grader.ts）从 metadata.cwd 运行：

• TypeScript：运行 bun test，扫描 **/*.{ts,js} 查找生成的文件
• Python：运行 uv run pytest（测试目录中需要有 pyproject.toml）
• 将测试输出和生成的文件内容发送给 Haiku，由其以 LLM-as-judge 的方式评分（0.0–1.0）
• 通过阈值约为 0.65；目标为 0.95

在 SKILL.md 中应避免以下常见失败模式：

• 缺少 pytest：始终包含将 pytest 列为开发依赖项的 pyproject.toml 资源
• 模块作用域环境变量检查：Python 导入应放在测试函数内，以避免收集错误
• 提示词过于规定：prompts.jsonl 应描述预期结果，而非实现步骤
• 工具自省：切勿指示 Agent 对 SDK 事件流或工具调用对象进行断言
• 开放式测试查询：“最新 AI 新闻”会产生不可预测的内容——应使用包含确定性关键词的事实性查询

---

示例：添加新的 Python 集成技能

给定：仅使用 Python，通过 You.com 搜索封装 httpx 库。

要创建的文件：

skills/ydc-httpx-integration/
├── SKILL.md
└── assets/
    ├── path_a_basic.py
    ├── test_integration.py
    └── pyproject.toml

tests/ydc-httpx-integration/
└── .gitkeep

创建测试目录：

mkdir -p tests/ydc-httpx-integration && touch tests/ydc-httpx-integration/.gitkeep

prompts.jsonl 条目：

{"id":"ydc-httpx-integration","input":["Using the ydc-httpx-integration skill, create a working Python application that calls the You.com search API directly with httpx and returns search results. Write integration tests that call the real API and verify the response contains expected keywords. Save everything to the tests/ydc-httpx-integration directory.","Extend the integration to also support content extraction from URLs. Update the integration tests to verify both search and content extraction work with live queries."],"metadata":{"cwd":"tests/ydc-httpx-integration","language":"python"}}