Manage shared AI agent skills, configs, and automation across multi-repo workspaces. Works with Cursor, Claude Code, Codex, Amp, and 40+ AI coding tools.
The problem: AI agents only see the repo they run in. An agent working in a frontend repo has no visibility into the backend, API contracts, or shared conventions -- so it assumes and hallucinates. On top of that, each developer configures AI tools differently, so skills, instructions, rules, and MCP servers drift between projects and team members.
The solution: A single workspace/ repo that acts as the canonical source. Running npm install mirrors configs to the parent root, symlinks skills and MCP servers for every AI tool, and installs git hooks to keep everything in sync.
Create a new workspace (one-time, by whoever sets it up):
mkdir ~/dev/<your-org> && cd ~/dev/<your-org>
npx aiworkspace init
cd workspace
git remote add origin <your-repo-url>
git push -u origin mainJoin an existing workspace (every other team member):
cd ~/dev/<your-org>
git clone <your-teams-workspace-repo> workspace
cd workspace && npm installnpm install restores skills from the lockfile, mirrors configs to the parent root, creates skill symlinks, and installs git hooks. See setup.md for the full guide — including MCP secrets (cp .env.example .env.local, restart editor).
~/dev/<your-org>/ <- open this in Cursor / your editor
├── workspace/ <- this repo
│ ├── root-config/ <- canonical source for root-level AI configs
│ │ ├── AGENTS.md <- standing instructions for all AI tools
│ │ ├── .agents/mcp.json <- canonical MCP servers (single source of truth)
│ │ ├── .agents/skills/ <- workspace-wide skills
│ │ ├── .mcp.json, .cursor/, .codex/, .vscode/ <- per-editor configs (symlinked or generated)
│ │ ├── .env.example <- template for MCP secrets (-> .env.local at root)
│ │ └── skills-lock.json <- lockfile for workspace-wide skills
│ ├── .agents/skills/ <- workspace project-specific skills
│ ├── scripts/ <- automation (setup, hooks, skill wrappers)
│ └── package.json
├── <project-a>/ <- your app / service / library
├── <project-b>/
└── ...
The setup script walks root-config/ generically. Add new config types (Cursor rules, Claude settings, Codex config) and they sync automatically with no script changes.
Run a tool's init inside root-config/ and its output mirrors to the workspace root like anything else. OpenSpec is the worked example — one spec tree shared across every repo.
- Git cannot see empty directories, so they never mirror — add a
.gitkeep. - Directories the workspace also populates, such as
.claude/skills/, are merged, not replaced.
A project directory can hold a workspace of its own — a team repo cloned with its own
workspace/root-config/. Setup treats that as a boundary: it stops at any directory that is, or
contains, a workspace repo and never links inside it. The whole subtree belongs to that workspace,
project repos several levels down included.
~/dev/<your-org>/
├── workspace/ <- this workspace, manages the tree below
├── <project-a>/ <- linked
└── <team-b>/ <- SKIPPED: has its own workspace
├── workspace/ <- ...here
└── <their-project>/ <- theirs to link, not ours
Run npm run skills:setup inside the nested workspace to manage that subtree. Explicit setup and
sync runs name each boundary they skip; the git hooks stay quiet.
Everything follows nearest-wins: the closer a file is to the code being changed, the higher its priority.
| What | Workspace-wide | Per-project |
|---|---|---|
| Instructions | root-config/AGENTS.md synced to root |
<project>/AGENTS.md |
| Skills | root-config/.agents/skills/ symlinked everywhere |
<project>/.agents/skills/ |
| Cursor rules | root-config/.cursor/rules/ symlinked |
<project>/.cursor/rules/ |
| Cursor settings | root-config/.cursor/settings.json symlinked |
— |
| MCP servers | root-config/.agents/mcp.json synced to root |
<project>/.cursor/mcp.json |
| Docs | docs/ repo (sibling) |
<project>/docs/ |
npm run skills:add -- <source> [--project <repo>] # add from registry
npm run skills:add -- owner/repo --skill <name> # pick from multi-skill repo
npm run skills:remove -- [<skill>] [--project <repo>] # remove
npm run skills:create -- --name my-skill # create manually
npm run skills:list # list installed
npm run skills:find # search skill registry
npm run skills:update # update all
npm run skills:check # check for available updates
npm run skills:setup # re-sync configs and symlinksWithout --project, skills install to root-config/.agents/skills/ (workspace-wide). With --project <repo>, they go to <repo>/.agents/skills/ (project-only).
Skills are tracked in skills-lock.json (source + hash). On npm install, they are restored from the lockfile automatically.
MCP servers give agents shared tools. Define them once in root-config/.agents/mcp.json and every editor picks them up — no per-developer setup. context7 (up-to-date library docs) ships bundled.
| File | Editor | How |
|---|---|---|
.agents/mcp.json |
— | canonical, edit this one |
.mcp.json |
Claude Code | symlink |
.cursor/mcp.json |
Cursor | generated on sync |
.vscode/mcp.json |
VS Code / Copilot | generated on sync |
.codex/config.toml |
Codex | generated on sync |
To add or change a server, edit .agents/mcp.json, then regenerate the twins and symlinks:
npm run syncSync refreshes bundled servers from the aiworkspace template and preserves any servers you added. Local edits to a bundled server are overwritten on the next sync — to override one for a single repo, use <project>/.cursor/mcp.json (nearest-wins).
To drop a bundled server entirely, list it in root-config/.agents/mcp-disabled.json ({ "disabled": ["context7"] }) — deleting it from .agents/mcp.json alone won't stick, since sync restores bundled servers from the template.
Secrets. Servers that need tokens read them from .env.local at the parent workspace root:
cp .env.example .env.local # then fill in tokens, and restart your editor
npm run mcp:check-secrets # verify tokens are presentStdio servers using ${VAR} are wrapped automatically to load .env.local. See setup.md §4.1 for HTTP Bearer servers in Cursor and OAuth sign-in for Codex.
Env var naming. If you load .env.local into your shell (via npm run mcp:install-shell or a manual source in ~/.zshrc), those keys become part of your login environment. Prefer a workspace-specific prefix on secret names in .env.example and mcp.json (e.g. ACME_SONAR_TOKEN instead of SONAR_TOKEN) so they do not collide with other tools or projects. Stdio-only secrets that stay inside the MCP env loader are less exposed, but a consistent prefix keeps Bearer and stdio configs aligned. To avoid a login profile entirely, see setup.md §4.1 (terminal launch).
Template upgrade — pull latest managed scripts/ when a new aiworkspace release is published:
npm run upgradeConfig sync — after editing root-config/ (especially .agents/mcp.json), regenerate MCP twins and parent-root symlinks without bumping the template:
npm run syncIf aiworkspace is in devDependencies, upgrade updates that package from npm and copies its scripts/ into yours (your team's version field stays independent). Otherwise the workspace falls back to git: upstream remote + upstream/main for scripts/. upgrade chains sync automatically. npx aiworkspace init sets upstream automatically. See setup.md for details.
- Node.js >= 18
- Git
agent-skills is a companion collection of reusable agent skills — browse on skills.sh. Install any of them with the same skills:add workflow documented above.
| Skill | What it does |
|---|---|
| production-grade | Engineering posture for non-trivial work: plan before code, simplest-correct solution first, production hardening patterns. |
| tribunal | Doer → verifier panel → consensus loop to gate deliverables before ship. |
More skills in the collection — see the full catalog.
OpenSpec works inside a workspace for spec-driven development — see Tools that write their own config.
npm run skills:add -- a-tokyo/agent-skills --skill production-gradeApache-2.0