Aiworkspace

AI Workspace

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, and rules 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 for every AI tool, and installs git hooks to keep everything in sync.

Quick Start

Create a new workspace (one-time, by whoever sets it up):

mkdir ~/dev/ && cd ~/dev/
npx aiworkspace init
cd workspace
git remote add origin 
git push -u origin main

Join an existing workspace (every other team member):

cd ~/dev/
git clone  workspace
cd workspace && npm install

npm install restores skills from the lockfile, mirrors configs to the parent root, creates skill symlinks, and installs git hooks. See [setup.md](setup.md) for the full guide — including [MCP secrets](setup.md#41-mcp-secrets) (cp .env.example .env.local, restart editor).

How It Works

~/dev//                       /                        /
└── ...

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.

Knowledge Hierarchy

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 | /AGENTS.md | | Skills | root-config/.agents/skills/ symlinked everywhere | /.agents/skills/ | | Cursor rules | root-config/.cursor/rules/ symlinked | /.cursor/rules/ | | Docs | docs/ repo (sibling) | /docs/ |

Skills

npm run skills:add --  [--project ]      # add from registry
npm run skills:add -- owner/repo --skill          # pick from multi-skill repo
npm run skills:remove -- [] [--project ]   # 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 symlinks

Without --project, skills install to root-config/.agents/skills/ (workspace-wide). With --project , they go to /.agents/skills/ (project-only).

Skills are tracked in skills-lock.json (source + hash). On npm install, they are restored from the lockfile automatically.

Upgrading

Template upgrade — pull latest managed scripts/ when a new aiworkspace release is published:

npm run upgrade

Config sync — after editing root-config/ (especially .agents/mcp.json), regenerate MCP twins and parent-root symlinks without bumping the template:

npm run sync

If 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](setup.md) for details.

Requirements

• Node.js >= 18
• Git

Related resources

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.

npm run skills:add -- a-tokyo/agent-skills --skill production-grade

License

Apache-2.0

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: a-tokyo
• Source: a-tokyo/aiworkspace
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.