claude-code-arcane 2.7.1 → 2.9.1

package/skills/hotfix/SKILL.md

@@ -19,7 +19,7 @@ allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
 
 ## Phase 2: Create Hotfix Record
 
-Draft record with: short description, date, severity, reporter, status IN PROGRESS, sections for Problem (player impact), Root Cause (fill during investigation), Fix (fill during implementation), Testing, Approvals (lead-programmer, qa-tester, producer checkboxes), Rollback Plan.
+Draft record with: short description, date, severity, reporter, status IN PROGRESS, sections for Problem (player impact), Root Cause (fill during investigation), Fix (fill during implementation), Testing, Approvals (qa-engineer, qa-director, delivery-manager checkboxes), Rollback Plan.
 
 Ask to write to `production/hotfixes/hotfix-[date]-[short-name].md`.
 
@@ -33,11 +33,19 @@ Minimal change only — NO refactoring, cleanup, or features alongside. Run targ
 
 ## Phase 5: Collect Approvals (Parallel)
 
-Spawn via Task: `lead-programmer` (correctness/side effects), `qa-tester` (regression tests), `producer` (deploy timing/comms). All three must APPROVE before proceeding.
+Spawn via Task, **only the ones installed in `.claude/agents/`** (check first: an uninstalled name falls back to a general-purpose agent that reads broadly and returns nothing useful):
+
+| Agent | Question to ask it |
+|-------|--------------------|
+| `qa-engineer` | correctness and side effects of the fix |
+| `qa-director` | regression scope: what else must be re-tested |
+| `delivery-manager` | deploy timing and comms |
+
+Every agent that ran must APPROVE before proceeding. If none is installed, do the three checks inline and record that in the hotfix record instead of claiming approvals that never happened.
 
 ## Phase 5b: QA Re-Entry Gate
 
-Spawn `qa-lead` with hotfix description, affected system, regression results, caller list (grep).
+Spawn `qa-director` (or `qa-engineer` if that is what is installed) with hotfix description, affected system, regression results, caller list (grep).
 
 | QA Verdict | Action |
 |------------|--------|

package/skills/patch-notes/SKILL.md

@@ -6,7 +6,8 @@ argument-hint: "[version] [--style brief|detailed|full]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Bash
 model: haiku
-agent: community-manager
+context: fork
+agent: release-manager
 ---
 
 ## Phase 1: Parse Arguments

package/skills/perf-profile/SKILL.md

@@ -4,7 +4,6 @@ description: "Performance profiling workflow: identify bottlenecks, measure agai
 category: "testing"
 argument-hint: "[system-name or 'full']"
 user-invocable: true
-agent: performance-analyst
 allowed-tools: Read, Glob, Grep, Bash
 ---
 

package/skills/prototype/SKILL.md

@@ -5,8 +5,6 @@ category: "design"
 argument-hint: "[concept-description] [--review full|lean|solo]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task
-agent: prototyper
-isolation: worktree
 ---
 
 ## Phase 1: Define the Question

package/skills/qa-plan/SKILL.md

@@ -5,7 +5,8 @@ category: "testing"
 argument-hint: "[sprint | feature: system-name | story: path]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, AskUserQuestion
-agent: qa-lead
+context: fork
+agent: qa-director
 ---
 
 # QA Plan

package/skills/retrospective/SKILL.md

@@ -5,9 +5,11 @@ category: "agile"
 argument-hint: "[sprint-N|milestone-name]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write
-context: |
-  !git log --oneline --since="2 weeks ago" 2>/dev/null
 ---
+## Commits de las ultimas 2 semanas
+
+!`git log --oneline --since="2 weeks ago" 2>/dev/null || echo "sin commits"`
+
 ## Phase 1: Parse & Check Existing
 
 Determine scope: sprint (`sprint-N`) or milestone. Check for existing retro (`production/retrospectives/retro-[slug]-*.md` or `production/sprints/sprint-[N]-retrospective.md`). If found → offer update existing or start fresh.

package/skills/security-audit/SKILL.md

@@ -5,7 +5,8 @@ category: "security"
 argument-hint: "[full | network | save | input | quick]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write, Task
-agent: security-engineer
+context: fork
+agent: security-architect
 ---
 
 # Security Audit

package/skills/skill-auditor/SKILL.md

@@ -38,7 +38,19 @@ Parse the YAML block between `---` markers. Check against our spec (see `referen
 | `user-invocable` | yes | present, boolean |
 | `allowed-tools` | yes | present, comma-separated list of valid tool names |
 
-Flag **alirezarezvani format** if frontmatter contains `license`, `metadata`, `version`, `author`, or `updated` fields -- these need conversion.
+Flag **legacy imported format** if frontmatter contains `version`, `author`, `updated`, `python-tools`, or `tech-stack` -- these need conversion.
+
+Do NOT flag `license` or `metadata`: both are official Claude Code fields. `metadata` is a free-form map that Claude Code deliberately ignores, and it is the correct home for repo-local keys.
+
+Also check the `agent:` / `context:` pair:
+
+| Check | Fail condition |
+|-------|----------------|
+| `agent:` needs `context: fork` | `agent:` present without `context: fork` -- the field is inert |
+| `context:` value | any value other than `fork` |
+| `agent:` target exists | the named agent has no file in `agents/` |
+| `agent:` reachable | a profile shipping this skill does not install the agent's division |
+| unknown field | any key outside the official list plus `category` |
 
 ### 1.2 Measure weight
 
@@ -77,7 +89,7 @@ Compute grade from checks:
 | **A** | All 5 frontmatter fields correct, <= 200 lines, 2+ sections, no hallucinations |
 | **B** | Frontmatter complete but minor issues (description too long, missing handoff) |
 | **C** | Frontmatter incomplete (1-2 missing fields) OR 201-400 lines |
-| **D** | Frontmatter uses alirezarezvani format OR 400+ lines OR hallucinations found |
+| **D** | Frontmatter uses legacy imported format OR `agent:` without `context: fork` OR 400+ lines OR hallucinations found |
 | **F** | No frontmatter at all OR file is empty/broken |
 
 ### 1.6 Output report
@@ -92,10 +104,10 @@ Given a path to a SKILL.md, apply fixes in order:
 
 ### 2.1 Convert frontmatter
 
-If alirezarezvani format detected (has `license`, `metadata`, `version`, `author`):
+If legacy imported format detected (has `version`, `author`, `updated`, `python-tools`, `tech-stack`):
 
 1. Keep `name` and `description` (trim description to under 200 chars if needed)
-2. Drop `license`, `metadata` block, `version`, `author`, `updated`, `python-tools`, `tech-stack`
+2. Drop `version`, `author`, `updated`, `python-tools`, `tech-stack`. Keep `license` and `metadata` -- both are official. Move any repo-local key into the `metadata:` map instead of deleting it.
 3. Add `category` -- infer from parent folder: `skills-backend` -> `"backend"`, `skills-ai` -> `"ai"`, etc.
 4. Add `user-invocable: true` (default; set `false` only for sub-skills under another skill's directory)
 5. Add `allowed-tools: Read, Glob, Grep, Bash` (default read-only set; upgrade to include `Write, Edit` if skill body contains authoring/generation instructions)

package/skills/skill-auditor/references/frontmatter-spec.md

@@ -1,113 +1,120 @@
 # Frontmatter Specification -- Arcane Skills
 
-This is the authoritative frontmatter format for all skills in the Claude Code Arcane repo.
+Formato de frontmatter para todas las skills del repo Claude Code Arcane.
 
-## Required Format
+**Fuente de verdad:** la lista de campos que Claude Code realmente lee está en
+`code.claude.com/docs/en/skills`. Este documento la refleja y agrega la única
+convención local del repo (`category`). No inventar campos: un campo que no está
+en la tabla de abajo lo ignora el runtime, y ese silencio es donde el drift se
+esconde.
 
-Every `SKILL.md` must begin with a YAML frontmatter block:
+## Formato requerido
 
 ```yaml
 ---
 name: skill-name
-description: "Brief 1-2 sentence description of what the skill does."
+description: "Qué hace la skill y cuándo usarla, 1-2 oraciones."
 category: "domain-name"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash
 ---
 ```
 
-## Field Definitions
-
-### `name` (required, string)
-
-- Must be kebab-case (lowercase, hyphens): `api-design`, `scaffold-go`, `mcp-server-builder`
-- Must match the directory name containing the SKILL.md
-- No quotes needed unless it contains special YAML characters
-
-### `description` (required, string)
-
-- 1-2 sentences explaining what the skill does and when to use it
-- Under 200 characters preferred, 300 max
-- Must be quoted (double quotes)
-- Should NOT just repeat the skill name ("MCP Server Builder" is bad)
-- Good: `"Design and ship production-ready MCP servers from OpenAPI contracts."`
-
-### `category` (required, string)
-
-- Matches the domain folder the skill lives in
-- Inferred from parent: `skills-backend/` -> `"backend"`, `skills-ai/` -> `"ai"`
-- Standard categories: `arcane`, `backend`, `frontend`, `ai`, `devops`, `security`, `testing`, `gamedev`, `agile`, `business`, `marketing-content`, `marketing-growth`, `marketing-seo`, `marketing-strategy`, `finance`, `regulatory`, `git`, `clevel-advisors`, `clevel-operations`
-
-### `user-invocable` (required, boolean)
-
-- `true` -- skill can be called directly by the user via `/skill-name`
-- `false` -- skill is a sub-skill, invoked only by a parent skill
-- Sub-skills live inside another skill's directory (e.g., `self-improving-agent/skills/review/SKILL.md`)
-
-### `allowed-tools` (required, comma-separated string)
-
-- Lists the Claude Code tools this skill is permitted to use
-- Read-only skills: `Read, Glob, Grep, Bash`
-- Authoring skills: `Read, Write, Edit, Bash, Glob, Grep`
-- Orchestration skills: `Read, Write, Edit, Bash, Glob, Grep, Task`
-- Valid tool names: `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `Task`, `WebFetch`, `WebSearch`, `NotebookEdit`
-
-### `argument-hint` (optional, string)
-
-- Shows usage pattern when user invokes help
-- Examples: `"<skill-name|+profile>"`, `"[rest|graphql] [resource-name]"`, `"scan <dir> | fix <path>"`
-
-## Alirezarezvani Format (needs conversion)
-
-Skills imported from `alirezarezvani/claude-skills` use a different frontmatter:
+## Campos oficiales de Claude Code
+
+Todos son opcionales para el runtime; las columnas "Arcane" marcan lo que este
+repo exige por convención propia.
+
+| Campo | Arcane | Qué hace |
+|-------|--------|----------|
+| `name` | **requerido** | Etiqueta mostrada en los listados. En skills personales o de proyecto el comando sale del nombre del directorio, no de este campo. |
+| `description` | **requerido** | Qué hace y cuándo usarla. Claude decide con esto si aplicar la skill. `description` + `when_to_use` se truncan juntos a 1.536 caracteres. |
+| `when_to_use` | opcional | Contexto extra de invocación: frases gatillo, ejemplos de pedido. Se anexa a `description` y cuenta para el tope de 1.536. |
+| `argument-hint` | opcional | Hint de autocompletado. Ej: `[issue-number]`, `[filename] [format]`. |
+| `arguments` | opcional | Declaración estructurada de argumentos. |
+| `user-invocable` | **requerido** | `false` cuando solo Claude debe invocarla: la oculta del menú `/`. Default `true`. |
+| `disable-model-invocation` | opcional | `true` impide que Claude la cargue sola. También impide precargarla en subagentes. |
+| `allowed-tools` | **requerido** | Tools que Claude puede usar sin pedir permiso durante el turno que invoca la skill. El permiso se limpia con el mensaje siguiente. |
+| `disallowed-tools` | opcional | Denylist de tools. |
+| `model` | opcional | Modelo para el turno en que la skill está activa. Con `context: fork`, define el modelo del subagente. |
+| `effort` | opcional | Nivel de esfuerzo de razonamiento. |
+| `context` | opcional | **Único valor válido: `fork`.** Corre la skill en un subagente forkeado. |
+| `agent` | opcional | Qué tipo de subagente usar. **Solo tiene efecto si `context: fork` está puesto.** |
+| `background` | opcional | Corre en background. |
+| `hooks` | opcional | Hooks con alcance de esta skill. |
+| `paths` | opcional | Paths asociados. |
+| `shell` | opcional | Shell para los `` !`comando` `` del body: `bash` (default) o `powershell`. |
+| `metadata` | opcional | Map YAML libre para datos propios. **Claude Code no actúa sobre su contenido** — es el lugar correcto para campos que solo lee tooling nuestro. Descarta el valor si no es un map. |
+| `license` | opcional | Licencia. |
+| `compatibility` | opcional | Compatibilidad declarada. |
+
+### `category` — convención local, no campo oficial
+
+`category` no existe en la doc de Claude Code: el runtime lo ignora. Arcane lo
+exige igual porque `src/skills-catalog.ts` y los profiles lo usan para agrupar.
+Es inocuo. Si en algún momento deja de usarse desde `src/`, moverlo a
+`metadata:` en vez de dejarlo suelto.
+
+Categorías estándar: `arcane`, `backend`, `frontend`, `ai`, `devops`,
+`security`, `testing`, `gamedev`, `agile`, `business`, `marketing-content`,
+`marketing-growth`, `marketing-seo`, `marketing-strategy`, `finance`,
+`regulatory`, `git`, `clevel-advisors`, `clevel-operations`, `observability`,
+`database`, `workflow`, `visualnovel`, `audio`.
+
+## Reglas por campo
+
+### `name`
+- kebab-case, y tiene que coincidir con el directorio que contiene el SKILL.md.
+
+### `description`
+- 1-2 oraciones. Bajo 200 caracteres preferido, 300 máximo.
+- Entre comillas dobles.
+- No repetir solo el nombre de la skill.
+- Poner el caso de uso principal primero: se trunca a 1.536 caracteres.
+
+### `allowed-tools`
+- Read-only: `Read, Glob, Grep, Bash`
+- Authoring: `Read, Write, Edit, Bash, Glob, Grep`
+- Orquestación: `Read, Write, Edit, Bash, Glob, Grep, Task`
+- Nombres válidos: `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `Task`,
+  `WebFetch`, `WebSearch`, `NotebookEdit`
+
+### `agent` + `context`
+Van siempre juntos. `agent:` sin `context: fork` **no hace nada**:
 
 ```yaml
----
-name: "skill-name"
-description: Long description...
-license: MIT
-metadata:
-  version: 1.0.0
-  author: Alireza Rezvani
-  category: business-growth
-  domain: customer-success
-  updated: 2026-02-06
-  python-tools: tool1.py, tool2.py
-  tech-stack: keyword1, keyword2
----
+# MAL - el agente declarado nunca entra en juego
+agent: qa-director
+
+# BIEN
+context: fork
+agent: qa-director
 ```
 
-### Conversion Rules
+Y el agente nombrado tiene que existir en `agents/` **y** su división tiene que
+estar en la lista `agents:` de todos los profiles que traen la skill. Si no, el
+fork cae en un agente genérico sin system prompt especializado.
 
-1. **Keep**: `name`, `description` (trim to 200 chars if needed)
-2. **Drop entirely**: `license`, `metadata` (and all nested: `version`, `author`, `updated`, `python-tools`, `tech-stack`, `domain`)
-3. **Add**: `category` -- infer from the `skills-*` parent folder, NOT from `metadata.category`
-4. **Add**: `user-invocable: true`
-5. **Add**: `allowed-tools` -- default `Read, Glob, Grep, Bash`; add `Write, Edit` if the skill body contains generation/authoring instructions
+## Inyección de contexto dinámico
 
-### Partially Converted Format
+No hay campo de frontmatter para esto. El mecanismo es `` !`comando` `` **en el
+body**, y la salida reemplaza el placeholder antes de que Claude vea la skill:
 
-Some skills were partially converted (have `name` and `description` but missing our required fields). These need the missing fields added:
+```markdown
+## Estado actual
 
-```yaml
----
-name: "mcp-server-builder"
-description: "MCP Server Builder"      # <- too short, needs expansion
----
+- Branch: !`git branch --show-current`
+- Sprints: !`ls production/sprints/ 2>/dev/null || echo "sin sprints"`
 ```
 
-Fix: add `category`, `user-invocable`, `allowed-tools`, and expand `description`.
+El `!` se reconoce solo al principio de línea o después de whitespace, y el
+comando va entre backticks. `!echo foo` sin backticks es texto literal.
 
-## Validation Checklist
+## Formato a convertir (legacy)
 
-When auditing frontmatter, check in order:
+Si el frontmatter tiene `version`, `author`, `updated`, `python-tools` o
+`tech-stack`, es formato importado y hay que convertirlo: esos campos no existen
+en la doc oficial ni en Arcane.
 
-1. Does the file start with `---` on line 1?
-2. Is there a closing `---` before the first `#` heading?
-3. Is `name` present and kebab-case?
-4. Does `name` match directory name?
-5. Is `description` present and substantive (not just the name)?
-6. Is `category` present?
-7. Is `user-invocable` present and boolean?
-8. Is `allowed-tools` present with valid tool names?
-9. Are there any alirezarezvani-only fields that should be removed?
+**`license` y `metadata` NO son parte de este grupo** — los dos son campos
+oficiales de Claude Code y no hay que tocarlos.

package/skills/slo-sli/SKILL.md

@@ -2,13 +2,13 @@
 name: slo-sli
 description: "Define and operate SLIs, SLOs, and error budgets for Educabot services (Go + TS, GCP, Prometheus). Trigger: SLO, SLI, error budget, burn rate."
 category: "observability"
-stack: Go, TypeScript, Prometheus, GCP Cloud Monitoring, Terraform, Alertmanager
-context: Educabot EdTech LatAm — servicios con peak en horario escolar AM
 argument-hint: "[service-name] [--availability|--latency|--error]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
 metadata:
   category: reliability
+  stack: Go, TypeScript, Prometheus, GCP Cloud Monitoring, Terraform, Alertmanager
+  business-context: Educabot EdTech LatAm — servicios con peak en horario escolar AM
   sources:
     - Google SRE Handbook (sre.google/sre-book)
     - Google SRE Workbook — Implementing SLOs

package/skills/sprint-plan/SKILL.md

@@ -5,9 +5,11 @@ category: "agile"
 argument-hint: "[new|update|status] [--review full|lean|solo]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion
-context: |
-  !ls production/sprints/ 2>/dev/null
 ---
+## Sprints existentes
+
+!`ls production/sprints/ 2>/dev/null || echo "sin sprints"`
+
 ## Phase 0: Parse Arguments
 
 Mode: `new`, `update`, or `status`. Resolve review mode: `--review` arg → `production/review-mode.txt` → default `lean`.

package/skills/story-readiness/SKILL.md

@@ -46,7 +46,7 @@ Resolve: `--review` arg → `production/review-mode.txt` → default `lean`.
 
 ## Phase 8: Director Gate
 
-Solo/lean → skip. Full → spawn `qa-lead` gate QL-STORY-READY with story title, ACs, dependency status, verdict. ADEQUATE → cleared. GAPS/INADEQUATE → surface to user.
+Solo/lean → skip. Full → spawn `qa-director` gate QL-STORY-READY with story title, ACs, dependency status, verdict. ADEQUATE → cleared. GAPS/INADEQUATE → surface to user.
 
 ## Protocol
 

package/skills/ux-design/SKILL.md

@@ -5,7 +5,8 @@ category: "design"
 argument-hint: "[screen/flow name] or 'hud' or 'patterns'"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Task
-agent: ux-designer
+context: fork
+agent: ux-lead
 ---
 # ux-design — UX Spec Authoring
 

package/skills/ux-review/SKILL.md

@@ -5,7 +5,8 @@ category: "design"
 argument-hint: "[file-path or 'all' or 'hud' or 'patterns']"
 user-invocable: true
 allowed-tools: Read, Glob, Grep
-agent: ux-designer
+context: fork
+agent: ux-lead
 ---
 # UX Review