136 lines
4.6 KiB
Markdown
136 lines
4.6 KiB
Markdown
# agent-install
|
|
|
|
Install `SKILL.md` files, MCP servers, and `AGENTS.md` guidance for any AI coding agent. Ships a **Node API** _and_ a **CLI** from a single package.
|
|
|
|
```bash
|
|
pnpm add agent-install
|
|
# or, as a one-shot CLI
|
|
npx agent-install@latest <skill|mcp|agents-md> <action>
|
|
```
|
|
|
|
## Node API
|
|
|
|
```ts
|
|
import { installSkillsFromSource } from "agent-install";
|
|
import { installMcpServer } from "agent-install/mcp";
|
|
import {
|
|
readAgentsMd,
|
|
upsertAgentsMdSection,
|
|
symlinkClaudeToAgents,
|
|
} from "agent-install/agents-md";
|
|
```
|
|
|
|
### Skills
|
|
|
|
```ts
|
|
await installSkillsFromSource({
|
|
source: "./skills/react-grab", // local, owner/repo, URL, or direct SKILL.md
|
|
agents: ["claude-code", "cursor"],
|
|
cwd: process.cwd(),
|
|
mode: "symlink", // or "copy"
|
|
});
|
|
```
|
|
|
|
One canonical copy lives at `.agents/skills/<name>`; agent-specific dirs (`.claude/skills`, `.cursor/skills`, etc.) receive relative symlinks, with automatic copy fallback on systems that don't allow them.
|
|
|
|
### MCP servers
|
|
|
|
```ts
|
|
installMcpServer({
|
|
source: "https://mcp.context7.com/mcp",
|
|
agents: ["cursor", "claude-code"],
|
|
name: "context7",
|
|
});
|
|
|
|
installMcpServer({
|
|
source: "@modelcontextprotocol/server-postgres",
|
|
agents: ["claude-code"],
|
|
env: { DATABASE_URL: "postgres://..." },
|
|
});
|
|
|
|
// Also available:
|
|
// listInstalledMcpServers, removeMcpServer, parseMcpSource,
|
|
// buildMcpServerConfig, mcpAgents, detectProjectInstalledMcpAgents, ...
|
|
```
|
|
|
|
14 MCP hosts across 3 config formats (JSON/JSONC with comment preservation, YAML, TOML). Per-agent `transformConfig` hooks handle Goose's `{cmd, envs, enabled, timeout}`, Zed's `{source: "custom", ...}`, OpenCode's `{type, command[], environment}`, Codex TOML layout, and VS Code's `{type: "stdio", ...}`.
|
|
|
|
Source types auto-detected by `parseMcpSource`:
|
|
|
|
| Input | Type | Becomes |
|
|
| --------------------------------------- | --------- | --------------------------------------- |
|
|
| `https://mcp.example.com/mcp` | `remote` | `{ type: "http", url }` |
|
|
| `@modelcontextprotocol/server-postgres` | `package` | `{ command: "npx", args: ["-y", pkg] }` |
|
|
| `"node /path/server.js --port 3000"` | `command` | `{ command: "node", args: [...] }` |
|
|
|
|
### AGENTS.md / CLAUDE.md / GEMINI.md
|
|
|
|
```ts
|
|
const { sections, content, path } = readAgentsMd();
|
|
|
|
upsertAgentsMdSection({
|
|
heading: "Testing",
|
|
body: "Run `pnpm test` before every commit.",
|
|
placement: "replace", // or "append" / "prepend"
|
|
level: 2,
|
|
});
|
|
|
|
// Agent-specific variants
|
|
upsertAgentsMdSection({
|
|
agent: "gemini-cli", // writes GEMINI.md
|
|
heading: "Setup",
|
|
body: "...",
|
|
});
|
|
|
|
// Claude Code still reads CLAUDE.md; point it at the canonical AGENTS.md
|
|
await symlinkClaudeToAgents({ overwrite: false });
|
|
```
|
|
|
|
Known variants (from `agentsMdFiles`):
|
|
|
|
| Agent | File |
|
|
| ----------- | --------------------- |
|
|
| universal | `AGENTS.md` |
|
|
| claude-code | `CLAUDE.md` |
|
|
| gemini-cli | `GEMINI.md` |
|
|
| cursor | `.cursor/rules/*.mdc` |
|
|
| codex | `AGENTS.md` |
|
|
| opencode | `AGENTS.md` |
|
|
| aider | `AGENTS.md` |
|
|
|
|
## CLI
|
|
|
|
```
|
|
agent-install skill <action> Manage SKILL.md files
|
|
add <source> -a, --agent, -s, --skill, -g, --global, --copy, -y, -l
|
|
init [name]
|
|
list -g, -a, --json
|
|
remove [skills...] -g, -a, -y
|
|
|
|
agent-install mcp <action>
|
|
add <source> -a, -g, -t|--transport, --header, --env, -n|--name, -y, --all
|
|
list -g, -a, --json
|
|
remove <name> -g, -a, -y
|
|
|
|
agent-install agents-md <action> (alias: doc)
|
|
init [--agent <agent>]
|
|
read [--agent <agent>] [-f <file>] [--json]
|
|
set-section <heading> --body | --body-file, --placement, --level, --agent, -f
|
|
remove-section <heading> --agent, -f
|
|
symlink-claude --overwrite, --backup <name>
|
|
```
|
|
|
|
## Subpath exports
|
|
|
|
| Import | Surface |
|
|
| ------------------------- | --------------------------------------------------- |
|
|
| `agent-install` | Skills (root default) |
|
|
| `agent-install/skill` | Alias of the root import |
|
|
| `agent-install/mcp` | MCP servers |
|
|
| `agent-install/agents-md` | AGENTS.md manipulation + `CLAUDE.md` symlink helper |
|
|
|
|
## References
|
|
|
|
- MCP build guide: [modelcontextprotocol.io/docs/develop/build-server](https://modelcontextprotocol.io/docs/develop/build-server)
|
|
- AGENTS.md spec: [agents.md](https://agents.md/)
|