Content
# @acosmi/skill-agent-mcp
🇨🇳 [🇬🇧 English README →](./README.en.md) · [GitHub](https://github.com/acosmi/skill-agent-mcp) · [Issues](https://github.com/acosmi/skill-agent-mcp/issues)
> **Expose "Skill-driven Intelligent Agent" capabilities to the outside world using the MCP protocol - SKILL.md serves as a unified fusion layer for three heterogeneous capabilities: tools, prompt fragments, and sub-agents.**
`@acosmi/skill-agent-mcp` packages the capability tree subsystem of [`@acosmi/agent`](https://github.com/acosmi/agent) behind a [Model Context Protocol](https://modelcontextprotocol.io) server, allowing external LLM clients (**Crab Code CLI**, **Crab Code Desktop**, Claude Desktop / Code, Cursor, etc.) to discover and call SKILL-driven capabilities through a **single, unified tool surface**.
SKILL.md is internally processed as a **unified fusion layer**: three modes (`prompt` / `tool` / `agent`) use the same template specification, which is internally dispatched by the server based on the `skill_mode` field. Externally, they are all presented as an MCP tool, and the caller does not need to care which one is currently being called.
## Why Create This Package
LLM clients currently have two main ways to extend capabilities:
1. **MCP servers** — The protocol specification is complete, but each tool must be manually written in the host language.
2. **In-prompt tool definitions** — Flexible, but LLM needs to remember the tool name and schema for each conversation.
`@acosmi/skill-agent-mcp` converges these two approaches: **SKILL.md files are tool definitions themselves**, and the server loads them once. The same SKILL.md template can express:
- **Prompt fragments**: zero-code, pure markdown.
- **Deterministic tool pipelines**: combine multiple steps to call registered tools, with input supporting template variable replacement.
- **Sub-agent specifications**: role, tool whitelist, token/time budget, used to derive sub-LLM sessions.
The MCP protocol surface remains unchanged: each SKILL is still an MCP tool to the client.
## Core Features
- ✅ **Three modes, one tool surface**: prompt / tool / agent are folded into one MCP tool per SKILL.
- ✅ **Monotonic permission decay**: sub-agents can never obtain tools that the parent agent does not have.
- ✅ **Skill-to-Tool compiler**: `tool_schema.steps[]` is compiled into callable combined tools.
- ✅ **`{{var.path}}` template engine**: pure variable references preserve original types; mixed strings are interpolated with `String(value)`.
- ✅ **Two transports**: stdio (Crab Code CLI / Desktop · Claude Desktop / Code) + Streamable HTTP (remote, recommended for SDK).
- ✅ **Natural language SKILL creation**: `skill_suggest` + `skill_generate` allow calling LLM to iterate on known good templates.
- ✅ **Workspace-root anti-overflow**: refuse to write outside the configured root directory, even if the client provides a malicious `tree_id` with `..`.
- ✅ **Atomic write JSON persistence**: combined tool storage is preserved across restarts (tmp + rename, permissions 0o600).
- ✅ **Zero built-in tools**: the framework is completely agnostic. Register your own tools through `ToolCallbackRegistry` (with built-in `InMemoryToolCallbackRegistry`).
- ✅ **TypeScript first**: `bun` runtime, `bunx tsc --noEmit` is fully green, with 136 test suites (about 200ms).
## Introduction to Three SkillMode Concepts
| Mode | MCP Tool Return | Typical Use |
|------|-------------|---------|
| `prompt` | SKILL body returned as-is (optionally with user's query prepended). | Static operation manuals, reference documentation, prompt fragments that need to be absorbed by the calling LLM as-is. |
| `tool` | Markdown representation of combined pipeline results. | Deterministic multi-step workflows, combining registered tools (e.g., "fetch → transform → write"). |
| `agent` | `[Agent Result] …` block, with structured `ThoughtResult`. | Long-running autonomous sub-agent sessions, with their own role + tool whitelist + token/time budget. |
The three modes can be mixed in the same SKILL library — the dispatcher will automatically parse based on `skill_mode` and the presence of `tool_schema` / `agent_config` fields. Templates for each mode are located in [`templates/`](./templates).
### Dispatcher Judgment Rules
1. Read the SKILL's `skill_mode` field, and use it if present.
2. Otherwise, if `tool_schema` exists → infer as `tool`.
3. Otherwise → default to `prompt`.
Validation will reject invalid combinations (e.g., `skill_mode=agent` but missing `agent_config`, or `skill_mode=tool` but also containing `agent_config`).
## Compatible LLM Clients
`@acosmi/skill-agent-mcp` implements the standard [Model Context Protocol](https://modelcontextprotocol.io), and in theory, any MCP-compatible client can connect. **Recommended order**:
| Client | Type | Connection Method | Notes |
|--------|-----|---------|------|
| 🦀 **Crab Code CLI** | Command-line / native terminal integration | One line `crabcode mcp add @acosmi/skill-agent-mcp` | acosmi's own product, zero adaptation required, native support for SKILL three-mode dispatch + built-in capability tree visualization + natural language SKILL creation |
| 🦀 **Crab Code Desktop** | Desktop application (Windows / macOS / Linux) | Settings → MCP Server → one-click installation | acosmi's own product, GUI integrated SKILL library management + agent_config visual editing + spawn_agent real-time audit panel |
| Claude Desktop | Anthropic official desktop client | Edit `claude_desktop_config.json` and add `mcpServers` section | See [`examples/claude-desktop-config.json`](./examples/claude-desktop-config.json) |
| Claude Code | Anthropic official CLI | `claude mcp add` command | stdio transport |
| Cursor | AI editor | Settings → MCP Servers | stdio + HTTP dual support |
| Continue.dev | VS Code / JetBrains plugin | Add `mcpServers` field to `~/.continue/config.json` | stdio transport |
| Self-built host | Any program using `@modelcontextprotocol/sdk` | Programmatically connect via `createServer()` | See "Quick Start: Embedded Call" below |
> 🦀 marks acosmi's own products, which are recommended for their out-of-the-box experience, deep integration, and priority support. Other clients connect through the standard MCP protocol, with the same functionality but requiring manual configuration.
## Status
**v1.0.0** — First release. The current stage remains local (`package.json#private: true`), and the functional surface is closed-loop for recorded features. Future versions will enhance `mcp/` + `e2e/` test coverage and add a built-in disk-scanning-based `SkillResolver`.
The `v1.0.0` git tag is on the `main` branch; release notes are in [CHANGELOG.md](./CHANGELOG.md).
## Installation (Local Development)
```bash
git clone https://github.com/acosmi/skill-agent-mcp.git
cd skill-agent-mcp
bun install
bun test # 136 pass / 2 skip / 0 fail / ~200 ms
bunx tsc --noEmit # 0 errors
```
Requires Bun ≥ 1.3 + Node ≥ 20 (for CLI shim).
## Quick Start: stdio MCP Server
Start with the example SKILL provided in the project (no host code required):
```bash
bun bin/acosmi-skill-agent-mcp \
--transport stdio \
--skills-dir ./examples/skills \
--templates-dir ./templates \
--state-dir ./.state
```
For Crab Code CLI / Desktop users, see Crab Code's built-in documentation for one-click completion with `crabcode mcp add @acosmi/skill-agent-mcp`. For Claude Desktop / Code users, paste the `mcpServers` section from [`examples/claude-desktop-config.json`](./examples/claude-desktop-config.json) into your client configuration (replacing absolute paths).
## Quick Start: Streamable HTTP Server
```bash
bun bin/acosmi-skill-agent-mcp \
--transport http \
--port 3030 \
--skills-dir ./examples/skills
# → [acosmi-skill-agent-mcp] streamable HTTP transport ready at http://127.0.0.1:3030/mcp
```
## Quick Start: Embedded Call (Programmatic Mount)
```ts
import { CapabilityTree, setTreeBuilder } from "@acosmi/skill-agent-mcp/capabilities";
import { ComposedToolStore } from "@acosmi/skill-agent-mcp/codegen";
import { staticSkillResolver, type SkillResolverWithBody } from "@acosmi/skill-agent-mcp/tools";
import { InMemoryToolCallbackRegistry } from "@acosmi/skill-agent-mcp/dispatch";
import { createServer, createStdioTransport } from "@acosmi/skill-agent-mcp/mcp";
import { promises as fs } from "node:fs";
// 1. Capability tree — empty here; production hosts will fill in real nodes.
const tree = new CapabilityTree();
setTreeBuilder(() => tree);
// 2. SKILL resolver — production hosts use disk scanning; demo uses static helper.
const skillSources: Record<string, string> = {
"tools/demo/hello": await fs.readFile("./skills/hello/SKILL.md", "utf-8"),
};
const skillResolver: SkillResolverWithBody = staticSkillResolver(skillSources);
// 3. Tool registry + combined tool storage (only required for tool-mode SKILL)
const toolRegistry = new InMemoryToolCallbackRegistry();
toolRegistry.register("echo", async (input) => String(input["text"] ?? ""));
const composedStore = new ComposedToolStore();
// 4. Construct and connect MCP server
const server = createServer({
tree,
skillsDir: "./skills",
templatesDir: "./templates",
stateDir: "./.state",
skillResolver,
toolRegistry,
composedStore,
// spawnSubagent: ...host-provided LLM loop... (only required for agent-mode SKILL)
});
await server.connect(createStdioTransport());
```
See the complete demo in [`examples/`](./examples).
## Registered MCP Tools
`createServer()` registers up to 11 MCP tools, each gated by the presence of optional dependencies. Minimal hosts have a small toolset; feature-complete hosts can enable all.
| Tool | Function | Dependency Gate |
|------|------|-----------------|
| `capability_manage` | View / validate / diagnose / patch capability tree (13 actions in one tool, passing JSON via `payload`) | Always registered |
| `tree_lookup_tool` | Resolve capability tree node ID + runtime ownership by tool name | Always registered |
| `tree_dump` | Export entire capability tree as JSON | Always registered |
| `tree_list_tier` | List all tool nodes under a specific intent tier (e.g., greeting / task_light / ...) | Always registered |
| `tree_list_bindable` | List nodes that support SKILL.md binding | Always registered |
| `skill_suggest` | Recommend the most suitable SKILL.md template based on free-form description | Always registered |
| `skill_generate` | Save LLM-drafted SKILL.md draft after validation | Always registered |
| `skill_manage` | List / read / update / delete / export SKILL.md | Always registered |
| `skill_activate` | Dispatch a SKILL through the dispatcher, verifying its runtime behavior | Requires `skillResolver` |
| `skill_parse` | Parse SKILL.md frontmatter, optionally executing SkillMode validation | Always registered |
| `spawn_agent` | Derive a sub-agent in agent mode | Requires `skillResolver` + `spawnSubagent` |
## Architecture (High-Level)
```
External LLM Clients (🦀 Crab Code CLI · 🦀 Crab Code Desktop · Claude Desktop / Code · Cursor · Continue.dev · ...)
│
│ MCP protocol (stdio or Streamable HTTP)
▼
┌─────────────────────────────────────────────┐
│ @acosmi/skill-agent-mcp · createServer() │
│ ├─ Register 11 MCP tools │
│ └─ Internal dispatch by skill_mode │
└─────────────────────────────────────────────┘
│
├─→ prompt mode → return SKILL body as-is
│
├─→ tool mode → ComposedSubsystem.executeTool
│ → Resolve {{var.path}} templates
│ → Call ToolCallbackRegistry.get(toolName)
│
└─→ agent mode → resolveSkillAgentCapabilities (monotonic decay)
→ DelegationContract.transitionStatus(active)
→ SpawnSubagent (host-provided LLM loop)
→ DelegationContract.transitionStatus(completed/failed)
```
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the complete subsystem diagram, 7-dimensional `CapabilityNode` shape, and `DelegationContract` state machine.
## Subsystem Structure
| Module | Function |
|------|------|
| `@acosmi/skill-agent-mcp/capabilities` | `CapabilityTree`, 7-dimensional node types, `setTreeBuilder`, `defaultTree`. Copied verbatim from `@acosmi/agent` v1.0. |
| `@acosmi/skill-agent-mcp/manage` | 13-action `executeManageTool` meta-tool (from v1.0). |
| `@acosmi/skill-agent-mcp/llm` | `LLMClient` interface + Anthropic / OpenAI dual-compatible reference adapters (OpenAI adapter compatible with Ollama OpenAI mode / vLLM / DeepSeek / OpenRouter / LiteLLM / Groq via `baseUrl`). |
| `@acosmi/skill-agent-mcp/skill` | Extended `SkillAgentConfig` (with 7 fields missing in v1.0) + multi-source SKILL.md aggregation + validation. |
| `@acosmi/skill-agent-mcp/dispatch` | `prompt` / `tool` / `agent` triple-mode server dispatcher + `DelegationContract` + monotonic permission decay. |
| `@acosmi/skill-agent-mcp/codegen` | SKILL → composite tool compiler + executor with `{{var.path}}` template engine. |
| `@acosmi/skill-agent-mcp/tools` | `skill_suggest` / `skill_generate` / `skill_manage` / `skill_activate` natural language SKILL toolset. |
| `@acosmi/skill-agent-mcp/mcp` | `createServer` factory + stdio / Streamable HTTP transport. |
---
## Documentation
- [`docs/SKILL-TEMPLATE.md`](./docs/SKILL-TEMPLATE.md) — Complete field syntax for SKILL.md (488-line specification).
- [`templates/`](./templates) — Five minimal skeletons (by `skill_mode` + intent).
- [`examples/`](./examples) — Three demo SKILLs + reference callback implementations + Claude Desktop configuration example.
- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — Subsystem boundaries + data flow.
- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — Development environment + commit guidelines.
- [`CHANGELOG.md`](./CHANGELOG.md) — Version history.
---
## Frequently Asked Questions (FAQ)
### Why not put all this in `@acosmi/agent`?
`@acosmi/agent` v1.0 is an "ability library" that doesn't assume any protocol. Forcing MCP SDK + zod on all v1.0 consumers would be regressive. By keeping MCP wrappers in this package, v1.0 remains protocol-agnostic.
### Can I use this outside of Claude / Anthropic?
Yes. The framework is fully provider-agnostic — `LLMClient` comes with Anthropic + OpenAI dual-compatible reference adapters (OpenAI adapter compatible with Ollama OpenAI mode / vLLM / DeepSeek / OpenRouter / LiteLLM / Groq via `baseUrl`). Any MCP-compatible client (🦀 **Crab Code CLI / Desktop** (recommended), Claude Desktop / Code, Cursor, Continue.dev, self-hosted) can connect via stdio or HTTP.
### Why `private: true`?
The v1.0 cycle is local-only. Removing `private` + registering an npm token is the only step left before publishing.
### How do I write my first SKILL?
1. Choose a starting point from [`templates/`](./templates) — or run `skill_suggest` on a running server.
2. Modify the frontmatter (`tree_id`, `summary`, `skill_mode`, fields required by the mode).
3. Save to `<skillsDir>/<tree_id>/SKILL.md`.
4. Validate with `skill_parse` MCP tool and `validate=true`.
### Can I add my own tools next to the built-in 11 MCP tools?
Yes — `createServer()` returns the underlying `McpServer` instance; call `.registerTool()` on it to add your own.
### How are child agents' permissions enforced?
`resolveSkillAgentCapabilities()` enforces **monotonic decay**: child agents' toolsets are always a subset of their parent's. The `agent_config.allow` list is intersected with the parent toolset and then added to — even if you declare `allow: [forbidden_tool]`, the child agent won't get that tool.
### What happens if a tool-mode SKILL step fails?
Each step's `on_error` determines the behavior: `abort` (default) returns immediately; `skip` records the error and continues; `retry` retries up to 2 times before giving up.
---
## Roadmap
| Milestone | Status | Description |
|--------|------|------|
| **v1.0** — First release | ✅ Published | 22 commits, 11 MCP tools, 136 test suites, complete TS surface. |
| **v1.1** — SkillResolver with built-in disk scanning | ⏳ Planned | Replaces demo's `staticSkillResolver`, recursively scans `--skills-dir`. |
| **v1.2** — mcp / e2e test coverage | ⏳ Planned | Adds `tests/mcp/` and `tests/e2e/`, covering mock McpServer + subprocess roundtrips. |
| **v1.3** — npm publish | ⏳ Planned | Removes `private: true`, generates `dist/` with `tsc`, registers npm token. |
| **v2.0** — Workspace depends on `@acosmi/agent` | ⏳ Planned | Once `@acosmi/agent` is on npm, replaces copied `capabilities/` + `manage/` + `llm/` with a single peer dependency. |
---
## Acknowledgements
- [`@acosmi/agent`](https://github.com/acosmi/agent) — The v1.0 ability library wrapped by this package.
- [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) — The MCP TypeScript SDK we integrated.
- crabclaw project (private) — The original Go implementation from which this package's translations were derived.
---
## License
Apache 2.0 — See [LICENSE](./LICENSE).
