agent-specs

Chinese documentation: README.zh-CN

agent-specs is a CLI for managing AGENTS.md files.

It can load AGENTS.md from a remote URL or a local file and install it either per-project or globally. In global mode, it detects installed AI agent clients on the local machine and symlinks a single shared rules file into each client’s native path so multiple agents can reuse the same source of truth. You can also target a specific agent explicitly.

The examples in this repository use Vercel's public agent-skills/AGENTS.md as a demo source. The project is inspired by Vercel Skills CLI.

Installation

# Run directly (recommended)
npx agent-specs <command>

# Or install globally
npm install -g agent-specs

Quick Start

# Project install: download AGENTS.md into the current directory
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md

# Reuse the existing project AGENTS.md and link it to Claude Code in this project
agent-specs add ./AGENTS.md -a claude-code

# Global install: write to ~/.agents/ and symlink to detected agent clients
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g

Commands

agent-specs add <source>

Install AGENTS.md from a remote URL or local file.

# Project install (default)
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md

# Project agent install: keep ./AGENTS.md as the source of truth
agent-specs add ./AGENTS.md -a claude-code

# Project agent install from another local file: write ./AGENTS.md, then symlink the selected agent path
agent-specs add ./docs/shared-rules.md -a claude-code

# Global install: write to ~/.agents/AGENTS.md and symlink to detected agents
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g

# Global install for a single agent
agent-specs add ./AGENTS.md -g -a claude-code

# Skip confirmation and overwrite existing files after backing them up
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g -y

Supported source formats:

| Format | Example | |------|------| | GitHub blob URL | https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md | | Short GitHub URL | https://github.com/vercel-labs/agent-skills/AGENTS.md | | Raw URL | https://raw.githubusercontent.com/vercel-labs/agent-skills/main/AGENTS.md | | Any URL | https://example.com/path/to/AGENTS.md | | Local relative path | ./AGENTS.md | | Local absolute path | /path/to/AGENTS.md | | File URL | file:///path/to/AGENTS.md |

Options:

| Option | Description | |------|------| | -g, --global | Install globally and symlink to detected agent clients | | -a, --agent <name> | Link to a specific agent client instead of relying on auto-detection. See Supported Agent Clients for valid values. | | -y, --yes | Skip confirmation and automatically back up then overwrite existing files |

agent-specs update

Re-load and update AGENTS.md from its original source.

agent-specs update
agent-specs update -g

agent-specs list

Show installation and symlink status.

agent-specs list
agent-specs list -g

agent-specs link

Detect agent clients again and recreate symlinks. This is useful after installing a new agent client. Explicitly configured global agents are also preserved.

agent-specs link
agent-specs link -y

agent-specs remove

Remove installed AGENTS.md files and related symlinks.

agent-specs remove
agent-specs remove -g
agent-specs remove -g -y

• If the install reused an existing AGENTS.md as the source of truth, remove preserves that file and removes only the symlink(s) plus CLI metadata.

How Global Install Works

~/.agents/AGENTS.md          <- source of truth
    ^ symlink
    |-- ~/.claude/CLAUDE.md
    |-- ~/.gemini/GEMINI.md
    |-- ~/.codex/AGENTS.md
    |-- ~/.config/amp/AGENTS.md
    |-- ~/.config/opencode/AGENTS.md
    |-- ~/.qwen/QWEN.md
    |-- ~/.roo/rules/AGENTS.md
    |-- ~/.continue/rules/AGENTS.md
    |-- ~/.augment/rules/AGENTS.md
    `-- ~/.kiro/steering/AGENTS.md

• Editing ~/.agents/AGENTS.md updates every linked agent immediately.
• Running agent-specs update -g refreshes the shared file without recreating symlinks.

How Project Agent Install Works

./AGENTS.md                <- source of truth
    ^ symlink
    `-- ./.claude/CLAUDE.md

• In project mode, -a <agent> keeps ./AGENTS.md as the source of truth.
• If <source> is another local file or a remote URL, the CLI writes its content into ./AGENTS.md first and then links the selected project agent path to it.
• If <source> is already ./AGENTS.md, the CLI reuses the existing file and remove preserves it.

Supported Agent Clients

| Agent | --agent | Detection Directory | Symlink Target | Filename | |-------|-----------|---------------------|----------------|----------| | Claude Code | claude-code | ~/.claude/ | ~/.claude/CLAUDE.md | CLAUDE.md | | Gemini CLI | gemini-cli | ~/.gemini/ | ~/.gemini/GEMINI.md | GEMINI.md | | Codex (OpenAI) | codex | ~/.codex/ | ~/.codex/AGENTS.md | AGENTS.md | | Amp | amp | ~/.config/amp/ | ~/.config/amp/AGENTS.md | AGENTS.md | | OpenCode | opencode | ~/.config/opencode/ | ~/.config/opencode/AGENTS.md | AGENTS.md | | Qwen Code | qwen-code | ~/.qwen/ | ~/.qwen/QWEN.md | QWEN.md | | Roo Code | roo-code | ~/.roo/ | ~/.roo/rules/AGENTS.md | AGENTS.md | | Continue | continue | ~/.continue/ | ~/.continue/rules/AGENTS.md | AGENTS.md | | Augment | augment | ~/.augment/ | ~/.augment/rules/AGENTS.md | AGENTS.md | | Kiro | kiro | ~/.kiro/ | ~/.kiro/steering/AGENTS.md | AGENTS.md |

The CLI only creates symlinks for agent clients that are actually detected on the machine. When -a, --agent <name> is provided, the CLI links the selected agent directly.

Conflict Handling

| Scenario | Default Behavior | -y Behavior | |------|---------|----------| | Source of truth already exists | Ask for confirmation | Back up to .backup and overwrite | | Agent path is a symlink | Replace it directly | Replace it directly | | Agent path is a regular file | Skip and report it | Back up to .backup and replace it |

Directory Structure

agent-specs/
|-- .github/
|   `-- workflows/
|       |-- ci.yml
|       `-- release.yml
|-- .gitignore
|-- bin/
|   `-- cli.mjs
|-- docs/
|   `-- README.zh-CN.md
|-- src/
|   |-- commands/
|   |   |-- add.ts
|   |   |-- link.ts
|   |   |-- list.ts
|   |   |-- remove.ts
|   |   `-- update.ts
|   |-- agents.ts
|   |-- cli.ts
|   |-- config.ts
|   |-- linker.ts
|   |-- prompt.ts
|   |-- source.ts
|   `-- types.ts
|-- build.config.mjs
|-- LICENSE
|-- package-lock.json
|-- package.json
|-- README.md
`-- tsconfig.json

Development

npm install
npm run build
npx tsx src/cli.ts --help
node bin/cli.mjs --help

License

MIT