{"id":47260613,"url":"https://github.com/zzgosh/agent-specs","last_synced_at":"2026-04-01T18:29:24.569Z","repository":{"id":344456685,"uuid":"1181827653","full_name":"zzgosh/agent-specs","owner":"zzgosh","description":"agent-specs is a CLI for managing AGENTS.md files.","archived":false,"fork":false,"pushed_at":"2026-03-19T16:00:09.000Z","size":88,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T07:10:28.474Z","etag":null,"topics":["agent","agent-rules","agents","apec","claude","gemini","specs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zzgosh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-14T17:19:13.000Z","updated_at":"2026-03-19T16:00:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zzgosh/agent-specs","commit_stats":null,"previous_names":["zzgosh/agent-specs","zzgosh/agent-spec"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/zzgosh/agent-specs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzgosh%2Fagent-specs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzgosh%2Fagent-specs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzgosh%2Fagent-specs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzgosh%2Fagent-specs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zzgosh","download_url":"https://codeload.github.com/zzgosh/agent-specs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzgosh%2Fagent-specs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agent-rules","agents","apec","claude","gemini","specs"],"created_at":"2026-03-14T22:56:26.849Z","updated_at":"2026-04-01T18:29:24.564Z","avatar_url":"https://github.com/zzgosh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-specs\n\nChinese documentation: [README.zh-CN](https://github.com/zzgosh/agent-specs/blob/main/docs/README.zh-CN.md)\n\n`agent-specs` is a CLI for managing `AGENTS.md` files.\n\nIt 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.\n\nThe examples in this repository use Vercel's public [agent-skills/AGENTS.md](https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md) as a demo source. The project is inspired by [Vercel Skills CLI](https://github.com/vercel-labs/skills).\n\n## Installation\n\n```bash\n# Run directly (recommended)\nnpx agent-specs \u003ccommand\u003e\n\n# Or install globally\nnpm install -g agent-specs\n```\n\n## Quick Start\n\n```bash\n# Project install: download AGENTS.md into the current directory\nagent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md\n\n# Reuse the existing project AGENTS.md and link it to Claude Code in this project\nagent-specs add ./AGENTS.md -a claude-code\n\n# Global install: write to ~/.agents/ and symlink to detected agent clients\nagent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g\n```\n\n## Commands\n\n### `agent-specs add \u003csource\u003e`\n\nInstall `AGENTS.md` from a remote URL or local file.\n\n```bash\n# Project install (default)\nagent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md\n\n# Project agent install: keep ./AGENTS.md as the source of truth\nagent-specs add ./AGENTS.md -a claude-code\n\n# Project agent install from another local file: write ./AGENTS.md, then symlink the selected agent path\nagent-specs add ./docs/shared-rules.md -a claude-code\n\n# Global install: write to ~/.agents/AGENTS.md and symlink to detected agents\nagent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g\n\n# Global install for a single agent\nagent-specs add ./AGENTS.md -g -a claude-code\n\n# Skip confirmation and overwrite existing files after backing them up\nagent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -g -y\n```\n\nSupported source formats:\n\n| Format | Example |\n|------|------|\n| GitHub blob URL | `https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md` |\n| Short GitHub URL | `https://github.com/vercel-labs/agent-skills/AGENTS.md` |\n| Raw URL | `https://raw.githubusercontent.com/vercel-labs/agent-skills/main/AGENTS.md` |\n| Any URL | `https://example.com/path/to/AGENTS.md` |\n| Local relative path | `./AGENTS.md` |\n| Local absolute path | `/path/to/AGENTS.md` |\n| File URL | `file:///path/to/AGENTS.md` |\n\nOptions:\n\n| Option | Description |\n|------|------|\n| `-g, --global` | Install globally and symlink to detected agent clients |\n| `-a, --agent \u003cname\u003e` | Link to a specific agent client instead of relying on auto-detection. See Supported Agent Clients for valid values. |\n| `-y, --yes` | Skip confirmation and automatically back up then overwrite existing files |\n\n### `agent-specs update`\n\nRe-load and update `AGENTS.md` from its original source.\n\n```bash\nagent-specs update\nagent-specs update -g\n```\n\n### `agent-specs list`\n\nShow installation and symlink status.\n\n```bash\nagent-specs list\nagent-specs list -g\n```\n\n### `agent-specs link`\n\nDetect agent clients again and recreate symlinks. This is useful after installing a new agent client. Explicitly configured global agents are also preserved.\n\n```bash\nagent-specs link\nagent-specs link -y\n```\n\n### `agent-specs remove`\n\nRemove installed `AGENTS.md` files and related symlinks.\n\n```bash\nagent-specs remove\nagent-specs remove -g\nagent-specs remove -g -y\n```\n\n- 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.\n\n## How Global Install Works\n\n```text\n~/.agents/AGENTS.md          \u003c- source of truth\n    ^ symlink\n    |-- ~/.claude/CLAUDE.md\n    |-- ~/.gemini/GEMINI.md\n    |-- ~/.codex/AGENTS.md\n    |-- ~/.config/amp/AGENTS.md\n    |-- ~/.config/opencode/AGENTS.md\n    |-- ~/.qwen/QWEN.md\n    |-- ~/.roo/rules/AGENTS.md\n    |-- ~/.continue/rules/AGENTS.md\n    |-- ~/.augment/rules/AGENTS.md\n    `-- ~/.kiro/steering/AGENTS.md\n```\n\n- Editing `~/.agents/AGENTS.md` updates every linked agent immediately.\n- Running `agent-specs update -g` refreshes the shared file without recreating symlinks.\n\n## How Project Agent Install Works\n\n```text\n./AGENTS.md                \u003c- source of truth\n    ^ symlink\n    `-- ./.claude/CLAUDE.md\n```\n\n- In project mode, `-a \u003cagent\u003e` keeps `./AGENTS.md` as the source of truth.\n- If `\u003csource\u003e` 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.\n- If `\u003csource\u003e` is already `./AGENTS.md`, the CLI reuses the existing file and `remove` preserves it.\n\n## Supported Agent Clients\n\n| Agent | `--agent` | Detection Directory | Symlink Target | Filename |\n|-------|-----------|---------------------|----------------|----------|\n| Claude Code | `claude-code` | `~/.claude/` | `~/.claude/CLAUDE.md` | `CLAUDE.md` |\n| Gemini CLI | `gemini-cli` | `~/.gemini/` | `~/.gemini/GEMINI.md` | `GEMINI.md` |\n| Codex (OpenAI) | `codex` | `~/.codex/` | `~/.codex/AGENTS.md` | `AGENTS.md` |\n| Amp | `amp` | `~/.config/amp/` | `~/.config/amp/AGENTS.md` | `AGENTS.md` |\n| OpenCode | `opencode` | `~/.config/opencode/` | `~/.config/opencode/AGENTS.md` | `AGENTS.md` |\n| Qwen Code | `qwen-code` | `~/.qwen/` | `~/.qwen/QWEN.md` | `QWEN.md` |\n| Roo Code | `roo-code` | `~/.roo/` | `~/.roo/rules/AGENTS.md` | `AGENTS.md` |\n| Continue | `continue` | `~/.continue/` | `~/.continue/rules/AGENTS.md` | `AGENTS.md` |\n| Augment | `augment` | `~/.augment/` | `~/.augment/rules/AGENTS.md` | `AGENTS.md` |\n| Kiro | `kiro` | `~/.kiro/` | `~/.kiro/steering/AGENTS.md` | `AGENTS.md` |\n\nThe CLI only creates symlinks for agent clients that are actually detected on the machine.\nWhen `-a, --agent \u003cname\u003e` is provided, the CLI links the selected agent directly.\n\n## Conflict Handling\n\n| Scenario | Default Behavior | `-y` Behavior |\n|------|---------|----------|\n| Source of truth already exists | Ask for confirmation | Back up to `.backup` and overwrite |\n| Agent path is a symlink | Replace it directly | Replace it directly |\n| Agent path is a regular file | Skip and report it | Back up to `.backup` and replace it |\n\n## Directory Structure\n\n```text\nagent-specs/\n|-- .github/\n|   `-- workflows/\n|       |-- ci.yml\n|       `-- release.yml\n|-- .gitignore\n|-- bin/\n|   `-- cli.mjs\n|-- docs/\n|   `-- README.zh-CN.md\n|-- src/\n|   |-- commands/\n|   |   |-- add.ts\n|   |   |-- link.ts\n|   |   |-- list.ts\n|   |   |-- remove.ts\n|   |   `-- update.ts\n|   |-- agents.ts\n|   |-- cli.ts\n|   |-- config.ts\n|   |-- linker.ts\n|   |-- prompt.ts\n|   |-- source.ts\n|   `-- types.ts\n|-- build.config.mjs\n|-- LICENSE\n|-- package-lock.json\n|-- package.json\n|-- README.md\n`-- tsconfig.json\n```\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpx tsx src/cli.ts --help\nnode bin/cli.mjs --help\n```\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzzgosh%2Fagent-specs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzzgosh%2Fagent-specs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzzgosh%2Fagent-specs/lists"}