{"_id":"@acosmi/skill-agent-mcp","_rev":"2-aae7fec8c4cf668baac07dd60718f94f","name":"@acosmi/skill-agent-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@acosmi/skill-agent-mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","agent","skill","skill-driven","capability-tree","anthropic","claude","ai-tools","typescript"],"author":{"name":"fushihua","email":"fgfncc@gmail.com"},"license":"Apache-2.0","_id":"@acosmi/skill-agent-mcp@1.0.0","maintainers":[{"name":"acosmi","email":"fushihua@acosmi.com"}],"homepage":"https://github.com/acosmi/skill-agent-mcp#readme","bugs":{"url":"https://github.com/acosmi/skill-agent-mcp/issues"},"bin":{"acosmi-skill-agent-mcp":"bin/acosmi-skill-agent-mcp"},"dist":{"shasum":"096648cfe79eac70bd0e3dda1b18173498eff3e5","tarball":"https://registry.npmjs.org/@acosmi/skill-agent-mcp/-/skill-agent-mcp-1.0.0.tgz","fileCount":238,"integrity":"sha512-tZP6OgxNqg020qoiwOA/+7lmxlv3r7LWvkKlNBmjpQUuIwIoho4B/rnr+SqMO/BgpO2tqmCZLndgbRg8FTfWnw==","signatures":[{"sig":"MEQCIAyTil6CXDpynvyDoAMtbWEPobhd9oWwmHPqnPKF26DXAiBSFJQUteIdV7nwj6o2fPyg2wFJuGw0uyvgTp8mLgeOag==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1129268},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./src/index.ts","engines":{"bun":">=1.3.0","node":">=20.0.0"},"exports":{".":{"bun":"./src/index.ts","types":"./dist/index.d.ts","import":"./dist/index.js"},"./llm":{"bun":"./src/llm/index.ts","types":"./dist/llm/index.d.ts","import":"./dist/llm/index.js"},"./mcp":{"bun":"./src/mcp/index.ts","types":"./dist/mcp/index.d.ts","import":"./dist/mcp/index.js"},"./skill":{"bun":"./src/skill/index.ts","types":"./dist/skill/index.d.ts","import":"./dist/skill/index.js"},"./tools":{"bun":"./src/tools/index.ts","types":"./dist/tools/index.d.ts","import":"./dist/tools/index.js"},"./manage":{"bun":"./src/manage/index.ts","types":"./dist/manage/index.d.ts","import":"./dist/manage/index.js"},"./codegen":{"bun":"./src/codegen/index.ts","types":"./dist/codegen/index.d.ts","import":"./dist/codegen/index.js"},"./dispatch":{"bun":"./src/dispatch/index.ts","types":"./dist/dispatch/index.d.ts","import":"./dist/dispatch/index.js"},"./capabilities":{"bun":"./src/capabilities/index.ts","types":"./dist/capabilities/index.d.ts","import":"./dist/capabilities/index.js"}},"gitHead":"d8665867e8aa52519b0e909f7daba8b717fce492","scripts":{"test":"bun test","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","start":"bun bin/acosmi-skill-agent-mcp","typecheck":"bunx tsc --noEmit","prepublishOnly":"bun run clean && bun run typecheck && bun test && bun run build"},"_npmUser":{"name":"acosmi","email":"fushihua@acosmi.com"},"repository":{"url":"git+https://github.com/acosmi/skill-agent-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server exposing skill-driven agent capabilities — SKILL.md as the unified fusion layer for tools, prompt fragments, and sub-agents.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.0","yaml":"^2.8.3","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/","provenance":false},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/skill-agent-mcp_1.0.0_1777625078421_0.43167785495971467","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@acosmi/skill-agent-mcp","version":"1.1.0","description":"MCP server exposing skill-driven agent capabilities — SKILL.md as the unified fusion layer for tools, prompt fragments, and sub-agents.","license":"Apache-2.0","author":{"name":"fushihua","email":"fgfncc@gmail.com"},"homepage":"https://github.com/acosmi/skill-agent-mcp#readme","repository":{"type":"git","url":"git+https://github.com/acosmi/skill-agent-mcp.git"},"bugs":{"url":"https://github.com/acosmi/skill-agent-mcp/issues"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/","provenance":false},"type":"module","main":"./dist/index.js","module":"./src/index.ts","types":"./dist/index.d.ts","bin":{"acosmi-skill-agent-mcp":"bin/acosmi-skill-agent-mcp","acosmi-skill-agent-mcp-bun":"bin/acosmi-skill-agent-mcp-bun"},"exports":{".":{"types":"./dist/index.d.ts","bun":"./src/index.ts","import":"./dist/index.js"},"./capabilities":{"types":"./dist/capabilities/index.d.ts","bun":"./src/capabilities/index.ts","import":"./dist/capabilities/index.js"},"./codegen":{"types":"./dist/codegen/index.d.ts","bun":"./src/codegen/index.ts","import":"./dist/codegen/index.js"},"./dispatch":{"types":"./dist/dispatch/index.d.ts","bun":"./src/dispatch/index.ts","import":"./dist/dispatch/index.js"},"./llm":{"types":"./dist/llm/index.d.ts","bun":"./src/llm/index.ts","import":"./dist/llm/index.js"},"./manage":{"types":"./dist/manage/index.d.ts","bun":"./src/manage/index.ts","import":"./dist/manage/index.js"},"./mcp":{"types":"./dist/mcp/index.d.ts","bun":"./src/mcp/index.ts","import":"./dist/mcp/index.js"},"./skill":{"types":"./dist/skill/index.d.ts","bun":"./src/skill/index.ts","import":"./dist/skill/index.js"},"./tools":{"types":"./dist/tools/index.d.ts","bun":"./src/tools/index.ts","import":"./dist/tools/index.js"}},"scripts":{"build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","prepublishOnly":"bun run clean && bun run typecheck && bun test && bun run build","test":"bun test","typecheck":"bunx tsc --noEmit","start":"bun src/cli/main.ts","start:built":"node bin/acosmi-skill-agent-mcp"},"engines":{"bun":">=1.3.0","node":">=20.0.0"},"keywords":["mcp","model-context-protocol","agent","skill","skill-driven","capability-tree","anthropic","claude","ai-tools","typescript"],"devDependencies":{"@types/bun":"latest","@types/express":"^4.17.21"},"peerDependencies":{"typescript":"^5"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","express":"^4.21.2","yaml":"^2.8.3","zod":"^3.25.0"},"_id":"@acosmi/skill-agent-mcp@1.1.0","gitHead":"c32f20aa02136c6233a25dc5d5a7e3f78c9154ee","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-bAMY7bceXU1Y9vjK/brvoJgvz34aETS/LAlVBKV3LfkDIcDKhl8l296ICK65p3SA2CMRNe3SpN269AFYKS3Dkg==","shasum":"1fa50a9a33ff0a043ca41100d37a6ac527d38e1c","tarball":"https://registry.npmjs.org/@acosmi/skill-agent-mcp/-/skill-agent-mcp-1.1.0.tgz","fileCount":235,"unpackedSize":1192161,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDtRwuUGPqSeO+3sOz0UD42V+TiENUiQRAopVEbjanM5AIgOf19Ge2hZTQIwwtOSrPmNQChOsl/qFKknemT7QOe8Wo="}]},"_npmUser":{"name":"acosmi","email":"fushihua@acosmi.com"},"directories":{},"maintainers":[{"name":"acosmi","email":"fushihua@acosmi.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skill-agent-mcp_1.1.0_1777633102637_0.5793521838983489"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-01T08:44:38.361Z","modified":"2026-05-01T10:58:22.905Z","1.0.0":"2026-05-01T08:44:38.609Z","1.1.0":"2026-05-01T10:58:22.813Z"},"bugs":{"url":"https://github.com/acosmi/skill-agent-mcp/issues"},"author":{"name":"fushihua","email":"fgfncc@gmail.com"},"license":"Apache-2.0","homepage":"https://github.com/acosmi/skill-agent-mcp#readme","keywords":["mcp","model-context-protocol","agent","skill","skill-driven","capability-tree","anthropic","claude","ai-tools","typescript"],"repository":{"type":"git","url":"git+https://github.com/acosmi/skill-agent-mcp.git"},"description":"MCP server exposing skill-driven agent capabilities — SKILL.md as the unified fusion layer for tools, prompt fragments, and sub-agents.","maintainers":[{"name":"acosmi","email":"fushihua@acosmi.com"}],"readme":"# @acosmi/skill-agent-mcp\n\n🇨🇳 中文文档（默认） · [🇬🇧 English README →](./README.en.md) · [GitHub](https://github.com/acosmi/skill-agent-mcp) · [Issues](https://github.com/acosmi/skill-agent-mcp/issues)\n\n> **以 MCP 协议对外暴露\"技能驱动智能体\"能力——SKILL.md 作为工具、提示词片段、\n> 子智能体三种异质能力的统一融合层。**\n\n`@acosmi/skill-agent-mcp` 把 [`@acosmi/agent`](https://github.com/acosmi/agent)\n的能力树子系统包装在\n[Model Context Protocol](https://modelcontextprotocol.io) 服务器后面，\n让外部 LLM 客户端（**Crab Code CLI**、**Crab Code Desktop**、Claude Desktop / Code、Cursor 等）\n通过**单一统一的工具表面**发现并调用 SKILL 驱动的能力。\n\nSKILL.md 在内部被处理为**统一融合层**：工具、提示词片段、子智能体三种模式\n（`prompt` / `tool` / `agent`）使用同一份模板规范，由服务端按 `skill_mode`\n字段做内部分发。对外它们一律呈现为一个 MCP 工具，调用方不必关心当前调\n的是哪一种。\n\n---\n\n## 为什么要做这个包\n\nLLM 客户端目前主要有两种扩展能力的方式：\n\n1. **MCP servers** — 协议规范完善，但每个工具都要在宿主语言里手写。\n2. **In-prompt tool definitions** — 灵活，但 LLM 每次对话都要重新记住\n   工具名和 schema。\n\n`@acosmi/skill-agent-mcp` 把这两者收敛：**SKILL.md 文件本身就是工具定义**，\n服务端一次加载即可。同一份 SKILL.md 模板可以表达：\n\n- **提示词片段**：零代码，纯 markdown。\n- **确定性工具流水线**：组合多步调用已注册工具，输入支持模板变量替换。\n- **子智能体规格**：角色、工具白名单、token/时长预算，用于派生子 LLM 会话。\n\nMCP 协议表面保持不变：每个 SKILL 在客户端看来仍然是**一个 MCP 工具**。\n\n---\n\n## 核心特性\n\n- ✅ **三种模式，一个工具表面**：prompt / tool / agent 折叠为每个 SKILL 一个 MCP 工具。\n- ✅ **权限单调衰减**：子智能体永远不能获得父智能体没有的工具。\n- ✅ **Skill-to-Tool 编译器**：`tool_schema.steps[]` 编译为可调用的组合工具。\n- ✅ **`{{var.path}}` 模板引擎**：纯变量引用保留原始类型；混合字符串通过 `String(value)` 插值。\n- ✅ **两种 transport**：stdio（Crab Code CLI / Desktop · Claude Desktop / Code）+ Streamable HTTP（远程，SDK 推荐替代 SSE）。\n- ✅ **自然语言 SKILL 创作**：`skill_suggest` + `skill_generate` 让调用 LLM 在已知良好模板上迭代。\n- ✅ **workspace-root 防越界**：拒绝写入配置根目录之外，即便客户端给出含 `..` 的恶意 `tree_id`。\n- ✅ **原子写 JSON 持久化**：组合工具存储跨重启保留（tmp + rename，权限 0o600）。\n- ✅ **零内置工具**：框架完全 agnostic。通过 `ToolCallbackRegistry` 注册自己的工具（自带 `InMemoryToolCallbackRegistry`）。\n- ✅ **TypeScript 优先**：`bun` 运行时，`bunx tsc --noEmit` 全绿，136 测试套件（约 200ms）。\n\n---\n\n## 三种 SkillMode 概念入门\n\n| 模式 | MCP 工具返回 | 典型用途 |\n|------|-------------|---------|\n| `prompt` | SKILL 正文原样返回（可选地在前面加用户的 query）。 | 静态操作手册、参考文档、需要由调用 LLM 原样吸收的提示词片段。 |\n| `tool` | 组合流水线每步结果的 markdown 表示。 | 确定性多步工作流，组合宿主已注册的工具（例如 \"fetch → transform → write\"）。 |\n| `agent` | `[Agent Result] …` 块，含结构化 `ThoughtResult`。 | 长期运行的自治子智能体会话，有自己的角色 + 工具白名单 + token/时长预算。 |\n\n可以在同一个 SKILL 库里混用三种模式 — dispatcher 会根据 `skill_mode`\n+ `tool_schema` / `agent_config` 字段是否存在自动解析。每种模式的模板\n都在 [`templates/`](./templates) 下。\n\n### dispatcher 的判定规则\n\n1. 读 SKILL 的 `skill_mode` 字段，存在则用它。\n2. 否则若存在 `tool_schema` → 推断为 `tool`。\n3. 否则 → 回退到 `prompt`。\n\n校验会拒绝不匹配的组合（如 `skill_mode=agent` 但缺 `agent_config`，\n或 `skill_mode=tool` 但同时含 `agent_config`）。\n\n---\n\n## 兼容的 LLM 客户端\n\n`@acosmi/skill-agent-mcp` 实现标准 [Model Context Protocol](https://modelcontextprotocol.io)，\n理论上任何 MCP 兼容客户端都能接入。**推荐顺序**：\n\n| 客户端 | 类型 | 接入方式 | 说明 |\n|--------|-----|---------|------|\n| 🦀 **Crab Code CLI** | 命令行 / 终端原生集成 | 一行 `crabcode mcp add @acosmi/skill-agent-mcp` | acosmi 自家产品，对本包零适配，原生支持 SKILL 三模式 dispatch + 内置能力树可视化 + 自然语言 SKILL 创作 |\n| 🦀 **Crab Code Desktop** | 桌面应用（Windows / macOS / Linux）| 设置 → MCP 服务器 → 一键安装 | acosmi 自家产品，GUI 集成 SKILL 库管理 + agent_config 可视化编辑 + spawn_agent 实时审计面板 |\n| Claude Desktop | Anthropic 官方桌面客户端 | 编辑 `claude_desktop_config.json` 加 `mcpServers` 段 | 见 [`examples/claude-desktop-config.json`](./examples/claude-desktop-config.json) |\n| Claude Code | Anthropic 官方 CLI | `claude mcp add` 命令 | stdio transport |\n| Cursor | AI 编辑器 | Settings → MCP Servers | stdio + HTTP 双支持 |\n| Continue.dev | VS Code / JetBrains 插件 | `~/.continue/config.json` 加 `mcpServers` 字段 | stdio transport |\n| 自建宿主 | 任何使用 `@modelcontextprotocol/sdk` 的程序 | 通过 `createServer()` 编程接入 | 见下方\"快速开始：嵌入式调用\" |\n\n> 🦀 标记为 acosmi 自家产品，开箱即用、深度集成、推荐首选。其他客户端通过标准 MCP 协议接入，功能相同但需手动配置。\n\n---\n\n## 状态\n\n**v1.0.0** — 首个发布版。当前阶段保持本地（`package.json#private: true`），\n功能层面对已记录的 surface 已闭环。后续版本会加强 `mcp/` + `e2e/` 测试\n覆盖度，并加入内置的基于磁盘扫描的 `SkillResolver`。\n\n`v1.0.0` git tag 在 `main` 分支；发布说明见\n[CHANGELOG.md](./CHANGELOG.md)。\n\n---\n\n## 安装（本地开发）\n\n```bash\ngit clone https://github.com/acosmi/skill-agent-mcp.git\ncd skill-agent-mcp\nbun install\nbun test          # 136 pass / 2 skip / 0 fail / ~200 ms\nbunx tsc --noEmit # 0 errors\n```\n\n要求 Bun ≥ 1.3 + Node ≥ 20（用于 CLI shim）。\n\n---\n\n## 快速开始：stdio MCP 服务器\n\n直接用项目自带的示例 SKILL 启动（不需要任何宿主代码）：\n\n```bash\nbun bin/acosmi-skill-agent-mcp \\\n  --transport stdio \\\n  --skills-dir ./examples/skills \\\n  --templates-dir ./templates \\\n  --state-dir ./.state\n```\n\nCrab Code CLI / Desktop 用户：见 Crab Code 内置文档 `crabcode mcp add @acosmi/skill-agent-mcp` 一键完成。\nClaude Desktop / Code 用户：把 [`examples/claude-desktop-config.json`](./examples/claude-desktop-config.json)\n中的 `mcpServers` 段贴入自己的客户端配置（替换里面的绝对路径）。\n\n---\n\n## 快速开始：Streamable HTTP 服务器\n\n```bash\nbun bin/acosmi-skill-agent-mcp \\\n  --transport http \\\n  --port 3030 \\\n  --skills-dir ./examples/skills\n# → [acosmi-skill-agent-mcp] streamable HTTP transport ready at http://127.0.0.1:3030/mcp\n```\n\n---\n\n## 快速开始：嵌入式调用（程序内挂载）\n\n```ts\nimport { CapabilityTree, setTreeBuilder } from \"@acosmi/skill-agent-mcp/capabilities\";\nimport { ComposedToolStore } from \"@acosmi/skill-agent-mcp/codegen\";\nimport { staticSkillResolver, type SkillResolverWithBody } from \"@acosmi/skill-agent-mcp/tools\";\nimport { InMemoryToolCallbackRegistry } from \"@acosmi/skill-agent-mcp/dispatch\";\nimport { createServer, createStdioTransport } from \"@acosmi/skill-agent-mcp/mcp\";\nimport { promises as fs } from \"node:fs\";\n\n// 1. 能力树 — 此处为空；生产宿主会塞入真实节点。\nconst tree = new CapabilityTree();\nsetTreeBuilder(() => tree);\n\n// 2. SKILL 解析器 — 生产宿主走磁盘扫描；demo 用 static helper。\nconst skillSources: Record<string, string> = {\n  \"tools/demo/hello\": await fs.readFile(\"./skills/hello/SKILL.md\", \"utf-8\"),\n};\nconst skillResolver: SkillResolverWithBody = staticSkillResolver(skillSources);\n\n// 3. 工具注册表 + 组合工具存储（仅 tool-mode SKILL 需要）\nconst toolRegistry = new InMemoryToolCallbackRegistry();\ntoolRegistry.register(\"echo\", async (input) => String(input[\"text\"] ?? \"\"));\n\nconst composedStore = new ComposedToolStore();\n\n// 4. 构造 + 连接 MCP 服务器\nconst server = createServer({\n  tree,\n  skillsDir: \"./skills\",\n  templatesDir: \"./templates\",\n  stateDir: \"./.state\",\n  skillResolver,\n  toolRegistry,\n  composedStore,\n  // spawnSubagent: ...宿主提供的 LLM loop... (仅 agent-mode SKILL 需要)\n});\n\nawait server.connect(createStdioTransport());\n```\n\n完整 demo 见 [`examples/`](./examples)。\n\n---\n\n## 注册的 MCP 工具\n\n`createServer()` 最多注册 11 个 MCP 工具，每个都按对应可选依赖是否\n存在做开关。极简宿主拿到的工具集很小；功能完整的宿主可以打开全部。\n\n| 工具 | 功能 | 依赖门控 |\n|------|------|---------|\n| `capability_manage` | 查看 / 校验 / 诊断 / 补丁 能力树（13 actions 折单工具，通过 `payload` 传 JSON） | 始终注册 |\n| `tree_lookup_tool` | 按工具名解析能力树节点 ID + 运行时归属 | 始终注册 |\n| `tree_dump` | 把整棵能力树以 JSON 形式导出 | 始终注册 |\n| `tree_list_tier` | 列出某意图层级（greeting / task_light / 等）下的全部工具节点 | 始终注册 |\n| `tree_list_bindable` | 列出所有支持 SKILL.md 绑定的节点 | 始终注册 |\n| `skill_suggest` | 根据自由描述推荐最合适的 SKILL.md 模板 | 始终注册 |\n| `skill_generate` | 校验后保存客户端 LLM 起草的 SKILL.md 草稿 | 始终注册 |\n| `skill_manage` | 列出 / 读取 / 更新 / 删除 / 导出 SKILL.md | 始终注册 |\n| `skill_activate` | 通过 dispatcher 派发一个 SKILL，验证其运行时行为 | 需 `skillResolver` |\n| `skill_parse` | 解析 SKILL.md frontmatter，可选执行 SkillMode 校验 | 始终注册 |\n| `spawn_agent` | 派生 agent 模式的子智能体 | 需 `skillResolver` + `spawnSubagent` |\n\n---\n\n## 架构（高层）\n\n```\n外部 LLM 客户端（🦀 Crab Code CLI · 🦀 Crab Code Desktop · Claude Desktop / Code · Cursor · Continue.dev · ...）\n              │\n              │  MCP 协议（stdio 或 Streamable HTTP）\n              ▼\n   ┌─────────────────────────────────────────────┐\n   │  @acosmi/skill-agent-mcp · createServer()   │\n   │  ├─ 注册 11 个 MCP 工具                      │\n   │  └─ 内部按 skill_mode 分发                   │\n   └─────────────────────────────────────────────┘\n              │\n              ├─→ prompt 模式 → 原样返回 SKILL body\n              │\n              ├─→ tool 模式  → ComposedSubsystem.executeTool\n              │                 → 解析 {{var.path}} 模板\n              │                 → 调用 ToolCallbackRegistry.get(toolName)\n              │\n              └─→ agent 模式 → resolveSkillAgentCapabilities（单调衰减）\n                              → DelegationContract.transitionStatus(active)\n                              → SpawnSubagent（宿主提供 LLM loop）\n                              → DelegationContract.transitionStatus(completed/failed)\n```\n\n完整子系统图 + 7 维 `CapabilityNode` 形态 + `DelegationContract` 状态机\n见 [ARCHITECTURE.md](./ARCHITECTURE.md)。\n\n---\n\n## 子系统结构\n\n| 模块 | 作用 |\n|------|------|\n| `@acosmi/skill-agent-mcp/capabilities` | `CapabilityTree`、7 维节点类型、`setTreeBuilder`、`defaultTree`。来自 `@acosmi/agent` v1.0 的逐字复制。 |\n| `@acosmi/skill-agent-mcp/manage` | 13-action `executeManageTool` 元工具（来自 v1.0）。 |\n| `@acosmi/skill-agent-mcp/llm` | `LLMClient` 接口 + Anthropic / OpenAI 双兼容参考适配器（OpenAI 适配器通过 `baseUrl` 覆盖兼容 Ollama OpenAI mode / vLLM / DeepSeek / OpenRouter / LiteLLM / Groq 等）。 |\n| `@acosmi/skill-agent-mcp/skill` | 扩展版 `SkillAgentConfig`（含 7 个 v1.0 缺失的字段）+ 多源 SKILL.md 聚合 + 校验。 |\n| `@acosmi/skill-agent-mcp/dispatch` | `prompt` / `tool` / `agent` 三模式服务端分发器 + `DelegationContract` + 权限单调衰减。 |\n| `@acosmi/skill-agent-mcp/codegen` | SKILL → 组合工具的编译器 + 含 `{{var.path}}` 模板引擎的执行器。 |\n| `@acosmi/skill-agent-mcp/tools` | `skill_suggest` / `skill_generate` / `skill_manage` / `skill_activate` 自然语言 SKILL 工具集。 |\n| `@acosmi/skill-agent-mcp/mcp` | `createServer` 工厂 + stdio / Streamable HTTP transport。 |\n\n---\n\n## 文档\n\n- [`docs/SKILL-TEMPLATE.md`](./docs/SKILL-TEMPLATE.md) — SKILL.md 完整字段语法（488 行规范）。\n- [`templates/`](./templates) — 五份精简骨架（按 `skill_mode` + 意图划分）。\n- [`examples/`](./examples) — 三个 demo SKILL + 参考回调实现 + Claude Desktop 配置示例。\n- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — 子系统边界 + 数据流。\n- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — 开发环境 + 提交规范。\n- [`CHANGELOG.md`](./CHANGELOG.md) — 版本历史。\n\n---\n\n## 常见问题（FAQ）\n\n### 为什么不把这些都放进 `@acosmi/agent`？\n\n`@acosmi/agent` v1.0 是不假设任何协议的\"能力库\"。把 MCP SDK + zod 强加\n给所有 v1.0 消费者会是退化。把 MCP 封装放在本包里，可以让 v1.0 保持\n协议中立。\n\n### 这能在 Claude / Anthropic 之外用吗？\n\n可以。框架完全 provider-agnostic — `LLMClient` 自带 Anthropic + OpenAI\n双兼容参考适配器（OpenAI 适配器通过 `baseUrl` 覆盖即可接 Ollama OpenAI\nmode / vLLM / DeepSeek / OpenRouter / LiteLLM 等任何 OpenAI 兼容服务），\n且任何 MCP 兼容客户端（🦀 **Crab Code CLI / Desktop**（首推）、\nClaude Desktop / Code、Cursor、Continue.dev、自建宿主）都可通过 stdio 或 HTTP 接入。\n\n### 为什么 `private: true`？\n\nv1.0 周期保持 local-only。删除 `private` + 注册 npm token 是 publish 前\n唯一剩下的步骤。\n\n### 怎么写第一个 SKILL？\n\n1. 从 [`templates/`](./templates) 选一个起点 — 或对运行中的服务器调\n   `skill_suggest`。\n2. 改动 frontmatter（`tree_id`、`summary`、`skill_mode`、对应模式所需字段）。\n3. 保存到 `<skillsDir>/<tree_id>/SKILL.md`。\n4. 用 `skill_parse` MCP 工具加 `validate=true` 校验。\n\n### 能不能在内置 11 个 MCP 工具旁边加自己的工具？\n\n可以 — `createServer()` 返回底层 `McpServer` 实例；直接在它上面调\n`.registerTool()` 添加即可。\n\n### 子智能体的权限是怎么强制的？\n\n`resolveSkillAgentCapabilities()` 强制实施**单调衰减**：子智能体的\n工具集永远是父集的子集。`agent_config.allow` 列表会先与父工具集求交集\n再加入 — 即便声明 `allow: [forbidden_tool]`，子智能体也不会获得这个\n工具。\n\n### tool-mode SKILL 某一步失败会怎么样？\n\n由每步的 `on_error` 决定：`abort`（默认）立即返回；`skip` 记录错误并\n继续下一步；`retry` 多重试 2 次后再放弃。\n\n---\n\n## 路线图\n\n| 里程碑 | 状态 | 说明 |\n|--------|------|------|\n| **v1.0** — 首个发布 | ✅ 已发布 | 22 commits、11 MCP 工具、136 测试套件、完整 TS surface。 |\n| **v1.1** — 内置磁盘扫描的 SkillResolver | ⏳ 计划中 | 替代 demo 的 `staticSkillResolver`，递归扫描 `--skills-dir`。 |\n| **v1.2** — mcp / e2e 测试覆盖度 | ⏳ 计划中 | 加 `tests/mcp/` 和 `tests/e2e/`，覆盖 mock McpServer + 子进程往返。 |\n| **v1.3** — npm publish | ⏳ 计划中 | 删除 `private: true`、用 `tsc` 生成 `dist/`、注册 npm token。 |\n| **v2.0** — workspace 依赖 `@acosmi/agent` | ⏳ 计划中 | 等 `@acosmi/agent` 上 npm 后，把复制的 `capabilities/` + `manage/` + `llm/` 替换为单一 peer dep。 |\n\n---\n\n## 致谢\n\n- [`@acosmi/agent`](https://github.com/acosmi/agent) — 本包包装的 v1.0\n  能力库。\n- [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)\n  — 我们集成的 MCP TypeScript SDK。\n- crabclaw 项目（私有）— 本包翻译来源的原始 Go 实现。\n\n---\n\n## 许可证\n\nApache 2.0 — 详见 [LICENSE](./LICENSE)。\n","readmeFilename":"README.md"}