codacle.
DocsIniciá sesión →

Docs · 30

Cómo escribir un kit.

Manifest schema, layout del directorio del kit, register-kit CLI, y cómo se ejecuta tu agente.

El layout de un kit

Un kit vive en su propio directorio (puede estar en kits/<id>/ del monorepo o externamente; register-kit toma una ruta absoluta). Estructura típica:

my-kit/
  manifest.yaml         # configuración + cross-refs a archivos del kit
  skills/
    analyze.md          # markdown con instrucciones del skill
    extract-forms.md
  agents/
    analyzer.md         # system prompt del agent
    mapper.md
  phases.yaml           # opcional — declarar las fases que vas a reportar
  inputs.yaml           # opcional — slots de upload del wizard

El register-kit CLI lee el manifest, valida con Zod, sube los skills y agents a Anthropic Managed Agents, y upsertea una row en la tabla kits.

El manifest

Schema validado en apps/worker/src/lib/kit-manifest-schema.ts. Mínimo viable:

kit:
  id: my-kit
  name: My Kit Name
  family: modernization        # o "understand"
  source: PL/SQL
  target: TypeScript
  source_logo: oracle          # un TechId de @/components/TechLogo
  target_logo: typescript
  tier: alpha                  # alpha | beta | general-availability
  expected_duration_minutes: 90
  description: One-line marketing blurb que aparece en el marketplace.

runtime:
  model: claude-opus-4-7       # default para todos los agents

agents:
  - id: analyzer
    type: entry                # uno solo con type=entry — punto de entrada
    system_prompt_file: agents/analyzer.md
    skills: [analyze, extract-forms]

skills:
  - id: analyze
    body_file: skills/analyze.md
  - id: extract-forms
    body_file: skills/extract-forms.md

inputs:
  - k: sources
    label: Código fuente
    help: Subí los .pls + .fmb del sistema.
    required: true
    accept: ".pls,.fmb,.zip"
    expects: archivos sueltos o un zip

Hay invariants cross-field que el schema valida:

  • Tiene que haber exactly one agent con type: entry.
  • Cada agent.skills[] tiene que referenciar un skill.id válido.
  • Cada phases[].k que reportes via report_phase tool tiene que estar declarado.

El agente

Tu agent es un system prompt (markdown) que tiene acceso a:

  1. Skills que mencionaste en agents[].skills — Anthropic los inyecta como "expertise" disponible.
  2. Custom tools que la plataforma despacha:
    • read_file(path) — lee archivos del workspace (sources subidas).
    • list_files(prefix) — explora la estructura.
    • emit_atom({type, id, label, body, refs}) — escribe un entity al Vault.
    • report_phase({k, status, note}) — actualiza el progreso visible.
    • write_output(path, content) — crea/sobreescribe un archivo del repo destino.

Estos no hace falta declararlos en el manifest — el worker los inyecta a toda session que arranca con un agent del kit.

El loop de ejecución

Cuando un workspace está en estado created y tiene sources subidas, el job analyze arranca:

  1. Worker abre Session en Anthropic con tu entry agent.
  2. Le pasa como user message el contexto del workspace: lista de archivos, kit_id, sources path.
  3. Stream-consumea eventos.
  4. Cada tool_use lo procesa: si es un tool nuestro, ejecuta y devuelve. Si Anthropic devuelve stop_reason='tool_use', manda otro messages.create con los tool_result agrupados.
  5. Cuando el agent termina (stop_reason='end_turn'), el worker hace commit final: marca workspace.status='analyzed', encola el próximo job si corresponde.

Registrar el kit

pnpm --filter web register-kit --kit-dir /ruta/a/my-kit

La CLI:

  1. Valida el manifest (Zod). Errores tempranos, no crea nada en Anthropic.
  2. Sube cada skill — devuelve skl_... ID.
  3. Crea environment — devuelve env_... ID.
  4. Crea cada agent — devuelve agent_... ID.
  5. Upsertea row kits(kit_id, version, manifest, skill_ids, agent_ids, environment_id, entry_agent_id).

Si bumpeás version en el manifest y volves a correr, queda una segunda row. Las dos coexisten — workspaces existentes siguen pinneados a la vieja. Para que workspaces nuevos usen la nueva, publicala desde /kits/[kit_id].

Validar sin registrar

pnpm --filter web validate-kit -- --kit-dir /ruta/a/my-kit

Sólo corre el schema Zod + chequeos de cross-refs (skills/agents/phases). Útil en CI antes de hacer push.

Iterar localmente

Mientras desarrollás el kit, el ciclo es:

  1. Cambiá los .md de skills/agents.
  2. Bumpea kit.version en el manifest (incluso a 0.1.0-rc1).
  3. pnpm --filter web register-kit --kit-dir ... — sube los cambios.
  4. En /kits/[kit_id], publicá la versión nueva (botón "cambiar a esta").
  5. Creá un workspace fresh desde el marketplace — usa la versión que acabás de publicar.

No hay hot-reload de prompts — cada cambio requiere re-register porque los skills/agents son recursos en Anthropic, no archivos locales del worker.