Skills como conocimiento institucional

Los skills son la forma en que una organización hace operativo su conocimiento institucional. Las instrucciones son explícitas, están controladas por versiones, se aplican ampliamente y se actualizan de forma centralizada cuando cambia la política. La regla general: escribe un skill para el conocimiento institucional que debe aplicarse de forma consistente; no escribas un skill para componentes que pertenecen en CLAUDE.md o en un prompt.

Primeros pasos

• Requisitos previos: Ninguno requerido. Tener un CLAUDE.md ayuda, porque mantiene el conocimiento de trabajo del agente en el repositorio, pero un skill no depende de ello.
• Infraestructura: Una política con un propietario designado y una fuente de verdad escrita.

Cómo ejecutarlo

1. Elige un fragmento de conocimiento que hoy se aplica de forma inconsistente. Podría ser un estándar de seguridad, una convención de diseño de API o una regla de marca.
2. Escríbelo como un skill, una carpeta que contiene un SKILL.md cuyo frontmatter indica cuándo se activa y cuyo cuerpo indica qué hacer. Un ingeniero lo escribe a partir de la fuente de verdad del propietario de la política, usando Claude para ayudar.
3. Coloca el skill en el repositorio en .claude/skills/<name>/ para que se distribuya junto con el código, o distribúyelo en toda la organización mediante un plugin.
4. Prueba que el skill se active. Pídele a Claude que realice la tarea relevante de diferentes maneras y confirma que el skill se carga cada vez.
5. Cuando la política cambie, cambia el skill y haz que el propietario de la política apruebe el cambio.
6. Los ingenieros obtienen la nueva versión automáticamente en su próxima sesión.

Cómo se ve

.claude/skills/secure-api-review/SKILL.md:

---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review
When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.
Run scripts/check-endpoints.sh and include its output in your summary.

Consideraciones de gobernanza

Un skill es un control, aunque de carácter consultivo. Hace que sea probable que Claude aplique la política mientras se escribe el código, pero nada obliga a una sesión a cumplirla. Una política que siempre debe cumplirse necesita algo determinista detrás del skill, como un hook que bloquee la acción o una revisión que vuelva a verificar la política en el PR. El skill hace que las infracciones sean poco frecuentes y el hook las hace casi imposibles. El hook detecta una infracción en la edición, y la misma verificación en el pull request detecta cualquier cosa que haya llegado a la rama de otra manera. Las invocaciones de skills se registran en las trazas de sesión, y el propietario de la política revisa los cambios de skills como si fueran código.

Cómo medirlo

• Indicador adelantado: El tiempo desde que el propietario de la política aprueba un cambio de política hasta que el skill actualizado se fusiona, tomado del PR en la carpeta del skill.
• Indicador rezagado: Los hallazgos de revisión de PR que citan la política, los cuales deberían tender a cero una vez que el skill esté aplicando la política mientras se escribe el código. Cuando los hallazgos no tienden a cero, o bien el skill no se está activando, o su texto se ha desviado de la política oficial.

Los hooks como barreras de protección en tiempo de construcción

Un skill es un control consultivo, mientras que un hook es la capa determinista que lo respalda. La mayoría de las acciones de Claude son ediciones de archivos y comandos de shell durante la implementación, por lo que la fase de construcción es donde los hooks suelen activarse con más frecuencia.

Los hooks de la fase de construcción pueden:

• Bloquear ediciones en rutas protegidas, como clases generadas o un paquete congelado
• Ejecutar el formateador y el linter después de las ediciones de archivos para que la desviación nunca se acumule
• Mantener las credenciales fuera del diff
• Respaldar cualquier skill cuya política deba cumplirse sin excepción

Un hook se ejecuta en cada acción que coincide con él, por lo que los hooks de la fase de construcción deben ser rápidos y estar limitados al archivo que cambió. Las verificaciones más pesadas, como la suite de pruebas completa, pertenecen al commit o al PR.

Este es el hook detrás de la regla 4 del skill secure-api-review mostrado anteriormente en esta página. El repositorio es de una aseguradora, y sus archivos de endpoints viven en claims-api/routes/. Después de cada edición a uno de esos archivos, el hook ejecuta scripts/check-endpoints.sh, el script en la raíz del repositorio que el skill ya nombra. Ese script falla cuando un campo etiquetado como pii en el esquema OpenAPI llega a una llamada de registro o a un error generado.

El hook está registrado en .claude/settings.json. La lista vacía de args hace que Claude Code ejecute el script directamente en lugar de a través de un shell:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/api-policy.sh",
            "args": [] }
        ]
      }
    ]
  }
}

El script del hook, .claude/hooks/api-policy.sh:

#!/bin/bash
# Respalda la regla 4 de la skill secure-api-review con el mismo script que ejecuta la skill.
file=$(jq -r '.tool_input.file_path')
case "$file" in
  "$CLAUDE_PROJECT_DIR"/claims-api/routes/*.py) ;;
  *) exit 0 ;;                                   # not an endpoint
esac
cd "$CLAUDE_PROJECT_DIR" || exit 2
if ! found=$(scripts/check-endpoints.sh "${file#"$CLAUDE_PROJECT_DIR"/}"); then
  echo "secure-api-review rule 4: a pii field reaches a log or an error message." >&2
  echo "$found" >&2
  exit 2
fi

Un hook que se ejecuta después de una edición no puede deshacerla, por lo que el código de salida 2 coloca el mensaje del script frente a Claude, quien puede entonces corregir la línea. Después de una edición que registra el nombre de un cliente, este es el mensaje que Claude ve del script:

secure-api-review rule 4: a pii field reaches a log or an error message.
claims-api/routes/status.py:10: policy_holder_name

Un hook Edit|Write no se activa cuando un comando de shell reescribe el archivo. Por esa razón, el mismo script también se ejecuta como una verificación obligatoria en cada pull request:

name: API policy
on: pull_request
jobs:
  check-endpoints:          # a required check in branch protection
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-endpoints.sh claims-api/routes/*.py

Un hook que solicita la aprobación de un humano pertenece a las puertas de control en Etapa 5: Despliegue, porque una solicitud de aprobación durante la construcción vuelve a poner a una persona en la ruta crítica de todas las sesiones que se ejecutan en paralelo.