Portable automation setup for Claude Code and compatible tools (Cursor, GitHub Copilot, Gemini CLI, Codex). Includes 13 agents, 12 skills, automation scripts, and git hooks that turn feature descriptions into Jira tickets, commits, PRs, and releases. Installable as opt-in Claude Code plugins — /plugin marketplace add dquancruz/AI-Setup — see "Installing agents & skills" below.
registry/ is the single source of knowledge (SSOT), tool-agnostic. install.sh and setup-repo.sh distribute it to two different destinations — see the "What goes where" table below.
AI-Setup/
├── install.sh # DEPRECATED — cp registry/agents + registry/skills → ~/.claude/ (GLOBAL)
├── setup-repo.sh # Distributes the rest of registry/ → the target repo (PER-REPO)
├── registry/ # SSOT — edited once, no duplication
│ ├── agents/ # 13 canonical agents → GLOBAL
│ ├── skills/ # 12 skills (folder/SKILL.md) → GLOBAL
│ ├── packs.yaml # Groups agents/skills into opt-in plugin packs (Fase 3)
│ ├── scripts/ # auto-commit.js, auto-pr.js, etc → PER-REPO
│ ├── rules/ # Path-scoped rules by domain → PER-REPO
│ ├── hooks/ # pre/post-tool-use (Claude only) → PER-REPO
│ └── templates/ # AGENTS.md, .mcp.json, githooks, GitHub Actions, local-docs → PER-REPO
├── plugins/ # GENERATED (committed) — one Claude Code plugin dir per pack, see below
├── .claude-plugin/marketplace.json # GENERATED (committed) — makes this repo `/plugin marketplace add`-able
├── tools/ # One adapter per tool (capabilities.yaml + enable.sh)
│ ├── claude/ # Wrapper around install.sh/setup-repo.sh + build-plugins.sh
│ ├── cursor/ # registry/rules → .cursor/rules/*.mdc, agents → Custom Modes
│ └── copilot/ # registry/* condensed → .github/copilot-instructions.md
├── lib/ # Shared condensation engine (condense.mjs)
├── docs/ # Reference guides + plans (some historical, marked as such)
├── CHANGELOG.md # Repo history
├── README.md
└── USAGE.md # Usage and installation guide
The preferred way to get agents and skills into Claude Code is the plugin marketplace, not
install.sh. This repo IS the marketplace — no separate repo to maintain:
/plugin marketplace add dquancruz/AI-Setup
/plugin install ai-setup-core@ai-setup
ai-setup-core covers the agents/skills every project wants (orchestrator, review, testing,
commits, PRs, releases). Install only the extra packs a given project actually needs —
ai-setup-backend, ai-setup-cloud, ai-setup-frontend, ai-setup-iot, ai-setup-security,
ai-setup-jira — see registry/packs.yaml for exactly what's in each. This is the fix for a
real cost the old monolithic install had: pulling in iot-backend-expert or immersive-3d on a
project that never touches hardware or 3D burns context budget for zero benefit.
plugins/* and .claude-plugin/marketplace.json are generated by tools/claude/build-plugins.sh
from registry/agents/, registry/skills/, and registry/packs.yaml — registry/ is still the
only place agent/skill content is authored. Unlike every other tools/*/enable.sh output, these
ARE committed to this repo (see build-plugins.sh's header comment for why: GitHub-sourced
/plugin marketplace add reads static files at a git ref, there's no build step in that flow).
CI regenerates and diffs them on every push, so plugins/ can't drift from registry/.
install.sh (copies all 13 agents + all 12 skills unconditionally to ~/.claude/, with
timestamped backups) still works and is kept for one cycle, but is deprecated in favor of the
above — see USAGE.md for the full migration.
Each registry/ subfolder has a single destination — this is what answers "does this live in ~/.claude/ or in every repo?":
registry/ |
Destination | Installed by |
|---|---|---|
agents/*.md |
~/.claude/agents/ — global, once per machine |
install.sh (deprecated) or /plugin install <pack>@ai-setup — see above |
skills/*/SKILL.md |
~/.claude/skills/<name>/ — global, once per machine |
install.sh (deprecated) or /plugin install <pack>@ai-setup — see above |
scripts/*.js |
<repo>/scripts/ — per-repo |
setup-repo.sh |
rules/*.md |
<repo>/.claude/rules/ (native) + <repo>/.cursor/rules/*.mdc (generated) — per-repo |
setup-repo.sh + tools/cursor/adapt/rule-to-mdc.sh |
hooks/{pre,post}-tool-use/*.sh |
<repo>/.claude/hooks/ — per-repo, Claude Code only |
setup-repo.sh |
templates/AGENTS.md |
<repo>/AGENTS.md — per-repo, only if it doesn't already exist |
setup-repo.sh |
templates/.mcp.json |
<repo>/.mcp.json — per-repo |
setup-repo.sh |
templates/githooks/*, templates/github/workflows/* |
<repo>/.githooks/ (wired via git config core.hooksPath), <repo>/.github/workflows/ — per-repo |
setup-repo.sh |
templates/local-docs/* |
<repo>/.local-docs/ — per-repo, gitignored, only if it doesn't already exist |
setup-repo.sh |
Simple rule: agents and skills are always global (installed once, serve any project); everything else in registry/ is per-repo (copied or re-rendered into every project that runs setup-repo.sh). The full detail of what each AI tool supports lives in tools/*/capabilities.yaml; the portability table below is its readable summary.
AGENTS.md is the Single Source of Truth for each project's instructions. No other instructions file is a hand-maintained copy of it, and — since Fase 2 of update-plan-aug-2026.md (2026-08-24) — none of them are symlinks either:
AGENTS.md ← edit only here
CLAUDE.md → real file, one line: `@AGENTS.md` (Claude Code's native import syntax)
GEMINI.md → real file, one line: `@AGENTS.md` (Gemini CLI supports the same import syntax)
.github/copilot-instructions.md → condensed rendering (lib/condense.mjs), NOT a copy of AGENTS.md — see "Portability by layer" below
.cursor/mcp.json → real copy of .mcp.json, regenerated by setup-repo.sh every run (Cursor reads this exact path, not a root .mcp.json)
An edit to AGENTS.md shows up in Claude Code and Gemini CLI immediately (both resolve @AGENTS.md at load time — no regeneration step, no symlink fragility on any platform, including Windows with no Developer Mode). .cursor/mcp.json and .github/copilot-instructions.md are regenerated by every setup-repo.sh run, so they can't go stale either. setup-portability.sh and the "Cross-tool portability" manual step it used to require no longer exist — see docs/archive/setup-portability.sh for why it was retired.
Source of truth: tools/*/capabilities.yaml (one per tool with a real adapter). Gemini CLI and Codex today only get the instructions layer rendered by this repo (they read AGENTS.md natively, or via GEMINI.md's @AGENTS.md import for Gemini CLI) — there's no tools/gemini/ or tools/codex/ yet; adding one is the pending Fase 5 in docs/AI-SETUP-PLAN-v2.md. Every cell below has a verification date + source in docs/tool-compatibility.md.
| Layer | Claude Code | Cursor | Copilot | Gemini CLI | Codex |
|---|---|---|---|---|---|
| Instructions | ✅ @AGENTS.md import (CLAUDE.md, native, no symlink) |
✅ native AGENTS.md |
✅ condensed → copilot-instructions.md |
✅ @AGENTS.md import (GEMINI.md, native, no symlink) |
✅ native AGENTS.md |
| Agents | ✅ native (real subagents) | ✅ Custom Mode (1 file per agent) | ✅ condensed (roster in instructions) | ❌ no adapter | ❌ no adapter |
| Skills | ✅ auto-discovery | ✅ native auto-discovery (.cursor/skills/; also reads ~/.claude/skills/ directly, no adapter needed) |
✅ condensed | ❌ no adapter | 🟡 native SKILL.md support exists (since ~Dec 2025) but this repo doesn't render into it yet — no tools/codex/ adapter |
| Rules | ✅ native .claude/rules |
✅ generated .mdc (rule-to-mdc.sh) |
✅ condensed | ❌ no adapter | ❌ no adapter |
| Hooks | ✅ native (PreToolUse/PostToolUse) |
✅ bridged (.cursor/hooks.json + hook-to-cursor.sh, since Cursor 1.7) |
❌ no equivalent | ❌ no equivalent | ❌ no equivalent |
| MCP | ✅ native .mcp.json |
✅ native .cursor/mcp.json |
🟡 partial (varies by surface) | ❌ no adapter | ❌ no adapter |
| Agent | Specialization |
|---|---|
agent-orchestrator |
Master orchestrator — entry point for full features |
solutions-expert |
System architecture and design |
ticket-orchestrator |
Jira hierarchy (Epic → Story → Task) |
backend-expert |
NestJS / FastAPI / MongoDB |
iot-backend-expert |
Raspberry Pi / GPIO / edge computing |
frontend-expert |
React / Next.js / Astro + a11y + design |
aws-architect |
AWS cloud architecture |
cdk-expert |
Infrastructure as Code (CDK) |
test-engineer |
Unit tests + coverage quality |
pr-manager |
Pull requests with the project's standard format |
code-reviewer-pro |
General review + light security scanning |
security-expert |
Deep AppSec (auth, crypto, IAM, secrets) |
documentation-generator |
Docs + semantic versioning + GitHub Releases |
| Skill | Domain |
|---|---|
auto-commit |
Conventional Commits |
pr-formatter |
PR format (the project's own standard) |
semantic-versioning |
SemVer + CHANGELOG + releases |
iot-backend |
IoT / Raspberry Pi |
auto-pr |
Automatic PR creation |
jira-integration |
Jira integration |
design-system |
Design presets (velocity / vice / quiet) |
immersive-3d |
WebGL / R3F / immersive experiences |
threat-modeling |
STRIDE threat modeling |
secure-coding |
OWASP Top 10 by stack |
cloud-iac-security |
CDK / AWS security |
local-docs |
.local-docs/ format + update rules (plan, architecture, security gaps, decisions) |
- Usage and installation guide →
USAGE.md - Contributing →
CONTRIBUTING.md - Repo change history →
CHANGELOG.md - Active roadmap (multi-tool architecture) →
docs/AI-SETUP-PLAN-v2.md— Fases 1-4 done, 5-6 pending - Cross-tool compatibility →
docs/tool-compatibility.md - Context budget →
docs/context-budget.md - GitHub Actions →
docs/GITHUB-ACTIONS-SETUP.md - MCP configuration →
docs/MCPS-configuracion-completa.md(historical — see the note at the top of the file) - Git Hooks → native, via
.githooks/+core.hooksPath(Fase 4.1) — seeregistry/templates/githooks/; the old Husky-based walkthrough isdocs/HOOKS-husky-complete.md(historical — see the note at the top of the file, anddocs/archive/husky/NOTE.mdfor why it was retired) - Original Nivel 3 setup →
docs/SETUP-COMPLETO-NIVEL-3.md(historical — see the note at the top of the file) - Original Nivel 3 index →
docs/INDICE-FINAL-NIVEL-3.md(historical — see the note at the top of the file) - 2026-06 restructure →
docs/RESTRUCTURE-2026-06.md(historical) - 2026-07 plan vs. reality →
docs/PLAN-VS-REALIDAD-2026-07.md(historical, a snapshot of a specific moment)