Tu equipo de agentes, en una carpetaYour agent team, in one folder

¿Qué máquina es?Which machine is it?

core siempre se instala. Para ver qué tiene esta máquina: cat ~/.ai-setup-profile.core is always installed. To see what this machine has: cat ~/.ai-setup-profile.

Cambiar despuésChange later

El código y sus docs los escribe un solo agente general (general / build) por ticket, en su worktree.Code and its docs are written by one general agent (general / build) per ticket, in its own worktree.

PrefijosPrefixes

¿Agente nuevo o skill?New agent or skill?

Agregar un agenteAdding an agent

---
name: sub-security
description: Auditoría de seguridad de un diff. Usar
  para "revisa seguridad", "¿es seguro?". Solo lectura.
mode: subagent        # subagent | primary | all
edit: none            # none | all | globs: */docs/*, *.md
bash: read-only       # read-only | checks | all
claude_tools: Read, Grep, Glob, Bash   # * = todas
tier: strong          # strong | balanced | fast
color: red
---

Eres auditor de seguridad. Asumes que hay fallos...
## Output
- Veredicto · tabla de hallazgos · qué no verificaste

---
name: sub-security
description: Security audit of a diff. Use for
  "check security", "is this safe?". Read-only.
mode: subagent        # subagent | primary | all
edit: none            # none | all | globs: */docs/*, *.md
bash: read-only       # read-only | checks | all
claude_tools: Read, Grep, Glob, Bash   # * = all
tier: strong          # strong | balanced | fast
color: red
---

You are a security auditor. Assume there are flaws...
## Output
- Verdict · findings table · what you did not verify

¿Cuál uso? Por tipo de tareaWhich one do I use? By kind of task

Referencia completaFull reference

instala https://github.com/owner/una-skill

install https://github.com/owner/some-skill

---
name: merge-pr
description: Actualiza un PR con develop y lo
  mergea por API. Usar con "mergear por API",
  "actualizar con develop", "quedó desactualizado".
---

# Mergear un PR
1. Comprueba que el CI pasó...
2. ...

---
name: merge-pr
description: Updates a PR with develop and
  merges it via API. Use for "merge via API",
  "update with develop", "branch is out of date".
---

# Merge a PR
1. Check that CI passed...
2. ...

core/    ─┐
<yours>/ ─┼─ install.py ─▶ build/AGENTS.md  ─▶ ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md
        ─┘      │       └▶ build/policy.json ─▶ guard + permisos + sandbox de cada herramienta
                 └▶ skills/agentes enlazados · notas ▶ $DEV/ai-notes/ · perfil ▶ ~/.ai-setup-profile

Cómo instalar cada combinación: sección Instalar.How to install each combination: Install section.

Crear una capa nuevaCreate a new layer

1. Crea una carpeta en ~/Dev/ai-setup/ con el nombre de la capa: php/, acme/… (minúsculas, números, - y _).Create a folder in ~/Dev/ai-setup/ named after the layer: php/, acme/… (lowercase, digits, - and _).
2. Mete dentro solo lo que necesites: policy.json (permisos), AGENTS.md (reglas), skills/, agents/ o notes/. La carpeta ya es una capa; no hay que registrarla en ningún sitio.Put in only what you need: policy.json (permissions), AGENTS.md (rules), skills/, agents/ or notes/. The folder is already a layer; nothing to register.
3. ./install.sh --with php. Una capa nueva nunca se instala sola: tienes que pedirla. Para quitarla: --uninstall php../install.sh --with php. A new layer is never installed on its own: you have to ask for it. To remove it: --uninstall php.

Una capa por contexto (empleador, cliente), no por lenguaje, salvo que el lenguaje traiga permisos o skills propias. Nombres reservados: adapters, docs, tests, build. Si dos capas tienen una skill con el mismo nombre, el instalador para.One layer per context (employer, client), not per language, unless the language brings its own permissions or skills. Reserved names: adapters, docs, tests, build. If two layers have a skill with the same name, the installer stops.

Extender: permisos, agentes y modelosExtend: permissions, agents and models

Todo va en tu capa; core/ no se toca. Después: ./install.sh --with <capa> y sesión nueva.All of it goes in your layer; core/ stays untouched. Then ./install.sh --with <layer> and a new session.

Reglas de permisos: son globs (*); ask y deny siempre ganan a allow; el instalador revisa la política y para con la regla que falla. Una regla para todos va en core/policy.json con un test en tests/test_guard.py.Permission rules: globs (*); ask and deny always win over allow; the installer checks the policy and stops at the offending rule. A rule for everyone goes in core/policy.json with a test in tests/test_guard.py.

Campos de un agente (frontmatter): name, description (obligatorios) · mode: subagent | primary | all · tier: strong | balanced | fast · effort: low | medium | high | xhigh (OpenCode lo ignora) · edit: none | all | globs · bash: read-only | checks | all · claude_tools: lista o * · color: yellow green blue purple red orange cyan gray. Un nombre de core no se puede reusar.Agent fields (frontmatter): name, description (required) · mode: subagent | primary | all · tier: strong | balanced | fast · effort: low | medium | high | xhigh (OpenCode ignores it) · edit: none | all | globs · bash: read-only | checks | all · claude_tools: list or * · color: yellow green blue purple red orange cyan gray. A core name cannot be reused.

Un ticket entero:A whole ticket: ticket-flow

Trabaja PROJ-123 con la skill ticket-flow

Work PROJ-123 with the ticket-flow skill

Tareas sueltasOne-off tasks

Carpetas de trabajo permitidas fuera del repo: las que una capa lista en work_dirs. $DEV es el dev_root que una capa fija en su policy.json (~ si ninguna): ahí van $DEV/handoffs (planes y traspasos), $DEV/ai-notes y $DEV/worktrees. Un host que no está en la lista del sandbox pregunta la primera vez. Lo que el guard no ve (base64, comandos armados en un script) está en tests/test_guard.py.Work folders allowed outside the repo: the ones a layer lists in work_dirs. $DEV is the dev_root a layer sets in its policy.json (~ if none): $DEV/handoffs (plans and handoffs), $DEV/ai-notes and $DEV/worktrees live there. A host missing from the sandbox list asks the first time. What the guard cannot see (base64, commands built in a script) is listed in tests/test_guard.py.

Cómo se arregla: pide a sub-review (o /code-review) que revise la rama; escribe el informe con el commit y el árbol que vio. Un informe vale si su commit es la cabeza de la rama o su árbol es el de esa cabeza (revisado antes de commitear). Salida de emergencia: AI_SETUP_NO_REVIEW=1 git merge x pasa a pedirte OK (🔴 high risk, "WITHOUT a review report") y queda en el log. Escribir en $DEV/reviews/ desde Bash también pregunta (🔴). Huecos conocidos: los comandos ! que escribes tú, falsificar el informe con la herramienta Write, y otras opciones con valor tras un wrapper (sudo -h host git merge; -u -g -U -C ya se entienden), GIT_DIR puesto con export/env, escrituras en reviews/ que no ve (mv de un informe fuera, cp -r sin barra final, dd of=, rutas relativas), y otras formas de aterrizar en main (/usr/bin/git merge, git fetch . x:main, git branch -f main x, cherry-pick, git push origin x:main), y la referencia remota local puede ser más vieja que lo que git pull origin x descarga (el guard juzga la que ve). Un git pull a secas en la rama por defecto cuando branch.<default>.merge apunta a otra rama la fusiona sin el gate (requiere un cambio previo de config). El Write de sub-review se limita a $DEV/reviews/ solo por instrucción (a los agentes de Claude no se les puede restringir la ruta), y una escritura relativa en reviews/ tras un cd no se ve.How to fix it: ask sub-review (or /code-review) to review the branch; it writes the report with the commit and tree it saw. A report counts when its commit is the branch head or its tree is that head's tree (reviewed before committing). Escape hatch: AI_SETUP_NO_REVIEW=1 git merge x turns the deny into an ask (🔴 high risk, "WITHOUT a review report") and is logged. Writing into $DEV/reviews/ from Bash also asks (🔴). Known gaps: ! commands you type yourself, forging the report with the Write tool, and other options with values after a wrapper (sudo -h host git merge; -u -g -U -C are understood), GIT_DIR set via export/env, writes into reviews/ it misses (mv of a report out, cp -r without a trailing slash, dd of=, relative paths), and other ways to land on main (/usr/bin/git merge, git fetch . x:main, git branch -f main x, cherry-pick, git push origin x:main), and the local remote-tracking ref may be older than what git pull origin x fetches (the guard judges the one it sees). A bare git pull on the default branch when branch.<default>.merge points to another branch merges it without the gate (needs a prior config change). The Write of sub-review is limited to $DEV/reviews/ by instruction only (Claude agents cannot be path-restricted), and a relative write into reviews/ after a cd is not seen.

Auditar un repo: python3 -I $AI_SETUP/core/skills/ai-audit/audit.py <repo>. Solo lee e imprime; las notas son heurísticas, no una calificación.Audit a repo: python3 -I $AI_SETUP/core/skills/ai-audit/audit.py <repo>. It only reads and prints; scores are heuristics, not a grade.

Máquina nuevaNew machine

1. git clone https://github.com/sebabottero/ai-setup.git ~/Dev/ai-setup (repo público, sin token). Si tus capas viven en otro repo, clónalo aparte (p. ej. ~/Dev/ai-setup-private) y pásalo con --layers-dir. No lo muevas después: los enlaces apuntan a esa ruta.git clone https://github.com/sebabottero/ai-setup.git ~/Dev/ai-setup (public repo, no token). If your layers live in another repo, clone it separately (e.g. ~/Dev/ai-setup-private) and pass it with --layers-dir. Don't move it afterwards: the links point to that path.
2. xcode-select --install e instala Homebrew (brew.sh). En Linux no hace falta brew: bootstrap.py lista los paquetes para tu gestor (apt, dnf…) y sigue con el resto. Después ./bootstrap.py --dry-run y ./bootstrap.py (con tus capas: --layers-dir ~/Dev/ai-setup-private --only core,<layer>): instala brew, Claude, OpenCode, LSP y corre install.sh. Al final imprime los logins que faltan.xcode-select --install and install Homebrew (brew.sh). On Linux brew is not needed: bootstrap.py lists the packages for your package manager (apt, dnf…) and goes on with the rest. Then ./bootstrap.py --dry-run and ./bootstrap.py (with your layers: --layers-dir ~/Dev/ai-setup-private --only core,<layer>): installs brew, Claude, OpenCode, LSP and runs install.sh. It ends by printing the logins still missing.
3. Vuelve a conectar los MCP de cada proyecto (claude mcp add … y después /mcp para el login). El instalador enlaza las notas de tus capas (<layer>/notes/) a $DEV/ai-notes/.Reconnect each project's MCPs (claude mcp add …, then /mcp to log in). The installer links your layers' notes (<layer>/notes/) to ~/ai-notes/.