Skill First. Build AI Apps.
AI Agent Skill 的 build system — 用组件拼装 AI 应用的开发工具链。
如果 Agent Skills 开放标准是 package.json，skillcraft 就是 npm + jest + eslint + webpack 的集合体，外加一个独创的 Product 组合层。
你不再写一个巨大的 prompt 来实现所有功能。你写多个独立 Skill，用 skit 校验、测试、编译，然后通过 Product 层把它们组合成一个完整的 AI 应用。
Agent Skill 生态已经爆发（Agent Skills 开放标准 已被 26+ 平台采纳），但没有开发工具链：
| 痛点 | 现状 |
|---|---|
| 质量无保障 | MIT + UCSB 对 34,000 个真实 Skill 的测试表明：大量 Skill 在现实条件下效果急剧下降 |
| 组合会冲突 | 多个 Skill 同时使用时，trigger 冲突、资源争抢导致失败 |
| 测试不存在 | 没有标准方法验证 prompt 是否正确工作 |
| 部署是手动活 | 每个平台格式不同，手动复制粘贴 |
| 无法组装产品 | 没有"如何把 5 个 Skill 拼装成一个应用"的解决方案 |
skillcraft 填补了从"写好一个 SKILL.md"到"交付一个可靠 AI 应用"之间的全部空白。
传统 AI 应用：一个巨大的 system prompt
skillcraft 的方式：Skill A + Skill B + Skill C = Product
↓ ↓
独立组件 声明式组合
| 能力 | 说明 | 竞品状态 |
|---|---|---|
| Product 组合层 | 声明式组装 framework 通用 Skill + 产品专属 Skill，local 自动覆盖 framework | 全网唯一 |
| 多平台适配 | 写一次 SKILL.md，编译部署到 Cursor / Claude / Codex / Copilot / OpenClaw | omniskill 做 registry，我们做 toolchain |
| 冲突检测 | 开发时拦截：ID 重复、trigger 冲突、资源锁重叠 | SpecWeave 做语义级，我们做结构级 |
| 行为测试 | LLM 当裁判，Markdown 写测试用例，模拟 Agent 启动全流程 | Agentest 测运行时，我们测 prompt 质量 |
| SKIT-LOCK | 文件系统级锁协议，防止多 Skill 并发写冲突 | 竞品均无类似机制 |
| 质量门控 | JSON Schema + Pydantic 双重校验 + 领域自定义质量门（如 thinking-completeness） | 新兴领域 |
| 文件驱动开发 | 人只写 DAILY.md，AI 自动分拣到各文件 | CodingWithFiles 要求人维护结构 |
| 增量审计 | skill-audit incremental 模式，只审计变更文件 | 竞品均无 |
| 选择性分发 | distributable 总开关 + 适配器 enabled 平台开关 | 竞品均无 |
pip install -e .
skit --helpskit init project my-ai-app
# 自动检测当前 IDE，创建完整目录结构 + 示例 Skillskit init skill list-viewer --trigger auto
# 生成 SKILL.md + config.json（417 行 Schema 校验通过）skit check config --strict # Schema + 文件结构 + Markdown 内容
skit check conflicts # ID 重复 / trigger 冲突 / 资源锁重叠skit test run # LLM 驱动的场景测试
skit test run --product novel-assistant # 产品级端到端测试skit link all --agent cursor # 直接模式：symlink
skit link all --agent cursor --compile # 编译模式：格式转换后部署
skit unlink <name> --agent cursor # 卸载链接skit status # 查看各平台链接状态
skit info # 项目元数据信息skillcraft/
├── skills/ ← 通用 Skill 组件池（12 个，所有产品可复用）
│ ├── task-executor/ ← 结构化多轮任务执行框架（5 阶段 + 三维思考）
│ ├── skill-audit/ ← Skill 质量审计器（全量 + 增量模式）
│ ├── create-skill/ ← Skill 开发框架（引导创建 + 模板 + 校验）
│ ├── daily-dispatch/ ← 文件驱动分拣器（人写一个，AI 分拣一切）
│ ├── doc-maintenance/ ← 文档拓扑维护（自动生成 + 缺口检测）
│ ├── global-review/ ← 全局审视（总结改动 + 一致性审查 + 发现缺漏）
│ ├── milestone/ ← 里程碑快照（语义化回溯 + 历史决策记录）
│ ├── product-dev/ ← 多 Skill 产品开发工作流管理
│ ├── roadmap-archive/ ← roadmap 文件归档（阶段归档 + 版本归档）
│ ├── skill-lint-fix/ ← lint 错误自动修复（Phase 命名 / frontmatter / 结构）
│ ├── skit-cli/ ← skit CLI 工具链使用指南
│ └── commit-msg/ ← git commit message 生成（过滤供应商文案）
│
├── products/ ← 产品目录（声明式组合）
│ └── novel-assistant/ ← AI 小说写作助手（示例产品）
│ └── meta.json ← 声明：复用了哪些框架 Skill + 自己有哪些
│
├── skit_cli/ ← CLI 工具链（init / check / link / unlink / test / list / info / status）
├── test-engine/ ← LLM 驱动的行为测试引擎
├── schema/ ← JSON Schema（完整结构约束）
├── docs/ ← 完整文档（13 篇）
└── roadmap/ ← 开发规划（DAILY / ROADMAP / BACKLOG / BUGS / SKILLS）
每个产品通过 meta.json 声明 Skill 依赖关系：
{
"name": "novel-assistant",
"skills": {
"from_framework": ["task-executor", "create-skill"],
"local": ["character-builder", "plot-generator"]
}
}| 字段 | 含义 |
|---|---|
from_framework |
从根 skills/ 池复用的通用 Skill |
local |
产品目录下的专属 Skill（同名时覆盖 framework 版本） |
这是 React 组件模型在 AI Skills 领域的首次应用——没有任何其他项目解决"如何把多个 Skill 拼装成一个可交付应用"的问题。
开发 → 校验 → 测试 → 部署
skit init skill <name> # 创建
skit check config --strict # 校验（Schema + 结构 + 内容）
skit check conflicts # 冲突检测（ID / trigger / 资源锁）
skit test run # 测试（LLM-as-judge 行为验证）
skit link all --agent cursor # 部署（支持 5 大平台）
skit unlink <name> --agent cursor # 卸载
skit status # 查看链接状态
skit info # 项目信息
AI 项目的开发轨迹极易丢失。一次对话、一个思路、一个被否决的方案，如果没记录下来，三个月后就再也无法回溯。
核心目标：尽最大可能保留项目开发轨迹。 格式、分类、命名，都是手段，不是目的。
因此我们采用"人只写一个文件"的工作流：
人：每天打开 roadmap/DAILY.md，什么都往里写（任务、想法、Bug、反馈）
AI：自动分拣 → NOTES.md / DECISIONS.md / BACKLOG.md / USER-FEEDBACK.md
AI：定期归档 → archive/（保留原文痕迹，确保可追溯）
人不管理分类，不管格式，不管该放哪个文件。人只负责思考，AI 负责整理。分拣完成后，AI 自动检查各文件的健康状态。
这是上下文工程的具体实践：当大模型上下文窗口有限时，文件系统是无限扩展的外部记忆。每个文件都是对话重启时的"断点续传"。
| 平台 | 项目路径 | 全局路径 | 编译格式 |
|---|---|---|---|
| Cursor | .cursor/skills/ |
~/.cursor/skills/ |
.mdc |
| Claude Code | .claude/skills/ |
~/.claude/skills/ |
.md |
| OpenAI Codex | .codex/skills/ |
~/.codex/skills/ |
.md |
| GitHub Copilot | .github/skills/ |
~/.github/skills/ |
.md |
| OpenClaw | .agents/skills/ |
~/.openclaw/skills/ |
.md |
每个 Skill 有两个文件：
SKILL.md— 给 Agent 看的提示词（YAML frontmatter + Markdown 正文）config.json— 给工具用的元数据（11 个顶级字段：triggers / adapters / resources / capabilities / dependencies / ui / testing / contract ...）
提示词和元数据分离，工具链不解析 prompt 内容，只读 config。
将 OS 级 mutex 语义首次应用到 LLM Agent 领域：
1. 执行前检查 .skit/LOCK 文件
2. 如果被其他 Skill 占用 → 进入等待模式
3. 不得修改业务代码
4. 完成后释放锁
编译时通过 --inject-safety-rail 注入到 Skill 正文末尾。
| 维度 | 传统单元测试 | skillcraft 测试引擎 |
|---|---|---|
| 测试对象 | 函数 / 类 | 完整 Agent 行为（所有 Skill 加载后） |
| 用例格式 | 代码（assert） | Markdown 场景文件 |
| 断言方式 | 精确值匹配 | LLM-as-judge 语义评估 |
| 覆盖类型 | 代码覆盖率 | 意图路由 / 工作流 / 边界条件 |
测试的是"prompt 写得对不对"，而非"Agent 执行得对不对"。
| Skill | 作用 |
|---|---|
| task-executor | 结构化多轮任务执行框架（5 阶段流程 + 三维度自审） |
| skill-audit | Skill 质量审计器（全量 + 增量模式 + 交叉审计） |
| create-skill | Skill 开发框架（引导创建 + 模板 + 校验 + 草稿构建） |
| daily-dispatch | 文件驱动分拣器（人写一个文件，AI 分拣一切） |
| doc-maintenance | 多 Skill 项目的文档拓扑维护 |
| global-review | 全局审视：总结改动、一致性审查、发现缺漏 |
| milestone | 项目开发里程碑快照和语义化回溯 |
| product-dev | 多 Skill 项目的开发工作流管理 |
| roadmap-archive | roadmap 文件归档（阶段归档 + 版本归档） |
| skill-lint-fix | lint 错误自动修复（Phase 命名 / frontmatter / 结构补全） |
| skit-cli | skit CLI 工具链使用指南 |
| commit-msg | git commit message 生成（过滤供应商文案） |
| Product | 说明 | 状态 |
|---|---|---|
| novel-assistant | AI 小说写作助手（示例产品） | 🟡 骨架阶段 |
| 你想做什么 | 去哪里 |
|---|---|
| 完整使用指南 | docs/USAGE.md |
| 新手入门教程 | docs/TUTORIAL.md |
| CLI 命令参考 | docs/CLI-COMMANDS.md |
| Skill 开发指南 | docs/SKILL-DEVELOPMENT.md |
| Product 开发指南 | docs/PRODUCT-DEVELOPMENT.md |
| 系统架构 | docs/ARCHITECTURE.md |
| 多平台适配器 | docs/ADAPTERS.md |
| 测试引擎 | docs/TESTING.md |
| config.json 参考 | docs/SKILL-CONFIG-REFERENCE.md |
| 常见问题 | docs/FAQ.md |
| 发布流程 | docs/RELEASE.md |
- Python 3.11+，构建工具：hatchling
- 依赖：typer / rich / pydantic / pyyaml / jsonschema
- 版本：0.3.0（新增 5 个内置 Skill：daily-dispatch、doc-maintenance、global-review、milestone、roadmap-archive、skit-cli，以及 skit info/status/unlink 命令；修复分拣逻辑和版本号不一致问题）
- 内置 Skill：12 个通用 Skill，每个拥有 SKILL.md + config.json + USAGE.md 三件套
- 已知短板：
- Product 层只有
novel-assistant骨架（meta.json），Product 专属 Skills 待创建 - Frontend Engine（Cockpit/Radar）已从核心规划中移除，UI-as-Config 不再是差异化方向
- SKIT-LOCK 是协议而非运行时守卫，依赖 Agent 自律执行
- 测试引擎依赖 LLM API，非确定性 + API 成本
skit test引擎待完善（benchmarks / evaluators / 测试场景模板）
- Product 层只有
Skill First. Build AI Apps.