Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2026 agent-spec contributors
Copyright (c) 2026 agent-specs contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
75 changes: 30 additions & 45 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# agent-spec
# agent-specs

Chinese documentation: [README.zh-CN](https://github.com/zzgosh/agent-spec/blob/main/docs/README.zh-CN.md)
Chinese documentation: [README.zh-CN](https://github.com/zzgosh/agent-specs/blob/main/docs/README.zh-CN.md)

`agent-spec` is a CLI for managing `AGENTS.md` files.
`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.

Expand All @@ -12,64 +12,49 @@ The examples in this repository use Vercel's public [agent-skills/AGENTS.md](htt

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

# Or install globally
npm install -g agent-spec
npm install -g agent-specs
```

## Migration from `agent-specs`

If you already installed the old package `agent-specs`, migrate to `agent-spec` before using the new docs and commands.

```bash
# Remove the old global package
npm uninstall -g agent-specs

# Install the renamed package
npm install -g agent-spec
```

- The npm package name changed from `agent-specs` to `agent-spec`.
- The CLI command also changed from `agent-specs` to `agent-spec`.

## Quick Start

```bash
# Project install: download AGENTS.md into the current directory
agent-spec add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
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-spec add ./AGENTS.md -a claude-code
agent-specs add ./AGENTS.md -a claude-code

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

## Commands

### `agent-spec add <source>`
### `agent-specs add <source>`

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

```bash
# Project install (default)
agent-spec add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
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-spec add ./AGENTS.md -a claude-code
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-spec add ./docs/shared-rules.md -a claude-code
agent-specs add ./docs/shared-rules.md -a claude-code

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

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

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

Supported source formats:
Expand All @@ -92,41 +77,41 @@ Options:
| `-a, --agent <name>` | Link to a specific agent client instead of relying on auto-detection |
| `-y, --yes` | Skip confirmation and automatically back up then overwrite existing files |

### `agent-spec update`
### `agent-specs update`

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

```bash
agent-spec update
agent-spec update -g
agent-specs update
agent-specs update -g
```

### `agent-spec list`
### `agent-specs list`

Show installation and symlink status.

```bash
agent-spec list
agent-spec list -g
agent-specs list
agent-specs list -g
```

### `agent-spec link`
### `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.

```bash
agent-spec link
agent-spec link -y
agent-specs link
agent-specs link -y
```

### `agent-spec remove`
### `agent-specs remove`

Remove installed `AGENTS.md` files and related symlinks.

```bash
agent-spec remove
agent-spec remove -g
agent-spec remove -g -y
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.
Expand All @@ -149,7 +134,7 @@ agent-spec remove -g -y
```

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

## How Project Agent Install Works

Expand Down Expand Up @@ -192,7 +177,7 @@ When `-a, --agent <name>` is provided, the CLI links the selected agent directly
## Directory Structure

```text
agent-spec/
agent-specs/
|-- .github/
| `-- workflows/
| |-- ci.yml
Expand Down
71 changes: 28 additions & 43 deletions docs/README.zh-CN.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# agent-spec
# agent-specs

English README: [README.md](../README.md)

Expand All @@ -12,64 +12,49 @@ English README: [README.md](../README.md)

```bash
# 直接使用(推荐)
npx agent-spec <command>
npx agent-specs <command>

# 或全局安装
npm install -g agent-spec
npm install -g agent-specs
```

## 从 `agent-specs` 迁移

如果你之前已经安装过旧包 `agent-specs`,请先迁移到 `agent-spec`,再使用新的文档和命令。

```bash
# 卸载旧的全局包
npm uninstall -g agent-specs

# 安装重命名后的新包
npm install -g agent-spec
```

- npm 包名已从 `agent-specs` 改为 `agent-spec`
- CLI 命令也已从 `agent-specs` 改为 `agent-spec`

## 快速开始

```bash
# 项目级:下载 AGENTS.md 到当前目录
agent-spec add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md

# 复用当前项目已有的 AGENTS.md,并链接到项目内的 Claude Code 路径
agent-spec add ./AGENTS.md -a claude-code
agent-specs add ./AGENTS.md -a claude-code

# 全局级:下载到 ~/.agents/ 并 symlink 到已检测到的 agent 客户端
agent-spec add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g
```

## 命令

### `agent-spec add <source>`
### `agent-specs add <source>`

从远程 URL 或本地文件安装 `AGENTS.md`。

```bash
# 项目级安装(默认)
agent-spec add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md

# 项目级定向安装:让 ./AGENTS.md 成为 truth source,并 symlink 到指定 agent 的项目路径
agent-spec add ./AGENTS.md -a claude-code
agent-specs add ./AGENTS.md -a claude-code

# 从其他本地文件导入到当前项目,再 symlink 到指定 agent
agent-spec add ./docs/shared-rules.md -a claude-code
agent-specs add ./docs/shared-rules.md -a claude-code

# 全局安装:写入 ~/.agents/AGENTS.md,并 symlink 到各 agent
agent-spec add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g

# 全局安装到指定 agent
agent-spec add ./AGENTS.md -g -a claude-code
agent-specs add ./AGENTS.md -g -a claude-code

# 跳过确认提示(已有文件时自动备份并覆盖)
agent-spec add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g -y
agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g -y
```

支持的 source 格式:
Expand All @@ -92,41 +77,41 @@ agent-spec add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -
| `-a, --agent <name>` | 定向安装到指定 agent,而不是依赖自动检测 |
| `-y, --yes` | 跳过确认,自动备份并覆盖已有文件 |

### `agent-spec update`
### `agent-specs update`

从原始来源重新读取并更新 `AGENTS.md`。

```bash
agent-spec update
agent-spec update -g
agent-specs update
agent-specs update -g
```

### `agent-spec list`
### `agent-specs list`

查看当前安装状态和 symlink 情况。

```bash
agent-spec list
agent-spec list -g
agent-specs list
agent-specs list -g
```

### `agent-spec link`
### `agent-specs link`

重新检测 agent 客户端并创建 symlink,适用于安装了新 agent 后需要补建链接的场景。通过 `-a` 显式配置过的全局 agent 也会被保留。

```bash
agent-spec link
agent-spec link -y
agent-specs link
agent-specs link -y
```

### `agent-spec remove`
### `agent-specs remove`

移除已安装的 `AGENTS.md` 及相关 symlink。

```bash
agent-spec remove
agent-spec remove -g
agent-spec remove -g -y
agent-specs remove
agent-specs remove -g
agent-specs remove -g -y
```

- 如果安装时复用了一个已经存在的 `AGENTS.md` 作为 truth source,`remove` 会保留该文件,只移除 symlink 和 CLI 元数据。
Expand All @@ -149,7 +134,7 @@ agent-spec remove -g -y
```

- 修改 `~/.agents/AGENTS.md` 后,已链接的 agent 会立即读取到新内容。
- 执行 `agent-spec update -g` 后,所有 symlink 目标会同步到最新内容,无需重新链接。
- 执行 `agent-specs update -g` 后,所有 symlink 目标会同步到最新内容,无需重新链接。

## 项目级定向安装工作原理

Expand Down Expand Up @@ -192,7 +177,7 @@ CLI 只会为检测到已安装的 agent 创建 symlink。
## Directory Structure

```text
agent-spec/
agent-specs/
|-- .github/
| `-- workflows/
| |-- ci.yml # PR 与 main 分支构建检查
Expand Down
10 changes: 5 additions & 5 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 6 additions & 6 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
{
"name": "agent-spec",
"version": "0.1.5",
"name": "agent-specs",
"version": "0.1.4",
"description": "CLI for managing AGENTS.md files",
"type": "module",
"bin": {
"agent-spec": "bin/cli.mjs"
"agent-specs": "bin/cli.mjs"
},
"exports": {
".": {
Expand Down Expand Up @@ -34,7 +34,7 @@
"unbuild": "^3.5.0"
},
"keywords": [
"agent-spec",
"agent-specs",
"agents",
"ai",
"cli",
Expand All @@ -43,10 +43,10 @@
],
"repository": {
"type": "git",
"url": "git+https://github.com/zzgosh/agent-spec.git"
"url": "git+https://github.com/zzgosh/agent-specs.git"
},
"bugs": {
"url": "https://github.com/zzgosh/agent-spec/issues"
"url": "https://github.com/zzgosh/agent-specs/issues"
},
"license": "MIT"
}
2 changes: 1 addition & 1 deletion src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ const pkg = require('../package.json')
const program = new Command()

program
.name('agent-spec')
.name('agent-specs')
.description('CLI for managing AGENTS.md files')
.version(pkg.version)

Expand Down
Loading