Agent-almanac review-skill-format

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/es/skills/review-skill-format" ~/.claude/skills/pjt222-agent-almanac-review-skill-format-499c49 && rm -rf "$T"

manifest: i18n/es/skills/review-skill-format/SKILL.md

source content

Revisar Formato de Habilidad

Validar un archivo SKILL.md frente al estándar abierto agentskills.io. Esta habilidad verifica la completitud del frontmatter YAML, la presencia de las secciones obligatorias, el formato de los pasos del procedimiento (bloques Esperado/En caso de fallo), los límites de recuento de líneas y la sincronización con el registro. Úsela antes de fusionar cualquier habilidad nueva o modificada.

Cuándo Usar

Una nueva habilidad ha sido creada y necesita validación de formato antes de fusionarse
Una habilidad existente ha sido modificada y necesita revalidación
Realizar una auditoría por lotes de todas las habilidades en un dominio
Verificar una habilidad creada por la metahabilidad
```
create-skill
```
Revisar la contribución de una habilidad de un colaborador en una pull request

Entradas

Obligatorio: Ruta al archivo SKILL.md (p. ej.,
```
skills/setup-vault/SKILL.md
```
)
Opcional: Nivel de estrictez (
```
lenient
```
o
```
strict
```
, predeterminado:
```
strict
```
)
Opcional: Si verificar la sincronización con el registro (predeterminado: sí)

Procedimiento

Paso 1: Verificar que el Archivo Existe y Leer su Contenido

Confirmar que el archivo SKILL.md existe en la ruta esperada y leer su contenido completo.

# Verificar que el archivo existe
test -f skills/<skill-name>/SKILL.md && echo "EXISTS" || echo "MISSING"

# Contar líneas
wc -l < skills/<skill-name>/SKILL.md

Esperado: El archivo existe y su contenido es legible. Se muestra el recuento de líneas.

En caso de fallo: Si el archivo no existe, verifique la ruta en busca de errores tipográficos. Verifique que el directorio de la habilidad existe con

ls skills/<skill-name>/

. Si falta el directorio, la habilidad aún no se ha creado — use primero

create-skill

Paso 2: Verificar los Campos del Frontmatter YAML

Analizar el bloque de frontmatter YAML (entre los delimitadores

---

) y verificar que todos los campos obligatorios y recomendados están presentes.

Campos obligatorios:

```
name
```
— coincide con el nombre del directorio (kebab-case)
```
description
```
— menos de 1024 caracteres, comienza con un verbo
```
license
```
— típicamente
```
MIT
```
```
allowed-tools
```
— lista separada por comas o espacios

Campos de metadatos recomendados:

```
metadata.author
```
— nombre del autor
```
metadata.version
```
— cadena de versión semántica
```
metadata.domain
```
— uno de los dominios listados en
```
skills/_registry.yml
```

metadata.complexity

— uno de:

basic

intermediate

advanced

```
metadata.language
```
— idioma principal o
```
multi
```
```
metadata.tags
```
— separado por comas, 3-6 etiquetas, incluye el nombre del dominio

# Verificar que los campos obligatorios del frontmatter existen
head -30 skills/<skill-name>/SKILL.md | grep -q '^name:' && echo "name: OK" || echo "name: MISSING"
head -30 skills/<skill-name>/SKILL.md | grep -q '^description:' && echo "description: OK" || echo "description: MISSING"
head -30 skills/<skill-name>/SKILL.md | grep -q '^license:' && echo "license: OK" || echo "license: MISSING"
head -30 skills/<skill-name>/SKILL.md | grep -q '^allowed-tools:' && echo "allowed-tools: OK" || echo "allowed-tools: MISSING"

Esperado: Los cuatro campos obligatorios presentes. Los seis campos de metadatos presentes.

name

coincide con el nombre del directorio.

description

tiene menos de 1024 caracteres.

En caso de fallo: Reportar cada campo faltante como BLOQUEANTE. Si

name

no coincide con el nombre del directorio, reportar como BLOQUEANTE con el valor esperado. Si

description

supera los 1024 caracteres, reportar como SUGERENCIA con la longitud actual.

Step 3: Locale-Specific Validation (Translations Only)

If the frontmatter contains a

locale

field, the file is a translated SKILL.md. Perform these additional checks. If no

locale

field is present, skip this step.

Translation frontmatter fields — Verify these five fields are present:
- ```
locale
```
  — target locale code (e.g.,
```
de
```
  ,
```
ja
```
  ,
```
zh-CN
```
  ,
```
es
```
  )
- ```
source_locale
```
  — origin locale (typically
```
en
```
  )
- ```
source_commit
```
  — commit hash of the English source used for translation
- ```
translator
```
  — who or what produced the translation
- ```
translation_date
```
  — ISO 8601 date of translation
Prose language scan — Sample 3-5 body paragraphs (outside code blocks, frontmatter, and headings). Verify the prose is written in the target locale, not English.
Code block identity check — Compare code blocks in the translated file against the English source. Code blocks must be identical (code is never translated).

Expected: All five translation fields present. Body paragraphs are in the target locale. Code blocks match the English source exactly.

On failure: Report missing translation fields as BLOCKING. If body paragraphs are in English despite a non-English

locale

, report as BLOCKING.

Paso 3: Verificar las Secciones Obligatorias

Verificar que las seis secciones obligatorias están presentes en el cuerpo de la habilidad (después del frontmatter).

Secciones obligatorias:

```
## When to Use
```
```
## Inputs
```
```
## Procedure
```
(con subsecciones
```
### Step N:
```
)
```
## Validation
```
(también puede aparecer como
```
## Validation Checklist
```
)
```
## Common Pitfalls
```
```
## Related Skills
```

# Verificar cada sección obligatoria
for section in "## When to Use" "## Inputs" "## Procedure" "## Common Pitfalls" "## Related Skills"; do
  grep -q "$section" skills/<skill-name>/SKILL.md && echo "$section: OK" || echo "$section: MISSING"
done

# La sección de validación puede usar cualquiera de los dos encabezados
grep -qE "## Validation( Checklist)?" skills/<skill-name>/SKILL.md && echo "Validation: OK" || echo "Validation: MISSING"

Esperado: Las seis secciones presentes. La sección de procedimiento contiene al menos un subencabezado

### Step

En caso de fallo: Reportar cada sección faltante como BLOQUEANTE. Una habilidad sin las seis secciones no cumple con el estándar agentskills.io. Proporcionar la plantilla de sección de la metahabilidad

create-skill

Paso 4: Verificar el Formato de los Pasos del Procedimiento

Verificar que cada paso del procedimiento sigue el patrón requerido: título del paso numerado, contexto, bloques de código y bloques Expected:/On failure:.

Para cada subsección

### Step N:

, verificar:

El paso tiene un título descriptivo (no solo "Step N")
Existe al menos un bloque de código o instrucción concreta
Un bloque
```
**Expected:**
```
está presente
Un bloque
```
**On failure:**
```
está presente

Esperado: Cada paso del procedimiento tiene los bloques Expected: y On failure:. Los pasos contienen código concreto o instrucciones, no descripciones vagas.

En caso de fallo: Reportar cada paso al que le falten Expected/On failure como BLOQUEANTE. Si los pasos contienen solo instrucciones vagas ("configurar el sistema apropiadamente"), reportar como SUGERENCIA con una nota para añadir comandos concretos.

Paso 5: Verificar el Recuento de Líneas

Verificar que el SKILL.md está dentro del límite de 500 líneas.

lines=$(wc -l < skills/<skill-name>/SKILL.md)
[ "$lines" -le 500 ] && echo "OK ($lines lines)" || echo "OVER LIMIT ($lines lines > 500)"

Esperado: El recuento de líneas es 500 o menos.

En caso de fallo: Si supera las 500 líneas, reportar como BLOQUEANTE. Recomendar usar la habilidad

refactor-skill-structure

para extraer bloques de código de más de 15 líneas a

references/EXAMPLES.md

. Reducción típica: 20-40% extrayendo ejemplos extendidos.

Paso 6: Verificar la Sincronización con el Registro

Verificar que la habilidad está listada en

skills/_registry.yml

bajo el dominio correcto con metadatos coincidentes.

Verificar:

El
```
id
```
de la habilidad existe bajo la sección de dominio correcta
El
```
path
```
coincide con
```
<skill-name>/SKILL.md
```
La
```
complexity
```
coincide con el frontmatter
La
```
description
```
está presente (puede estar abreviada)
El recuento
```
total_skills
```
en la parte superior del registro coincide con el recuento real de habilidades

# Verificar si la habilidad está en el registro
grep -q "id: <skill-name>" skills/_registry.yml && echo "Registry: FOUND" || echo "Registry: NOT FOUND"

# Verificar la ruta
grep -A1 "id: <skill-name>" skills/_registry.yml | grep -q "path: <skill-name>/SKILL.md" && echo "Path: OK" || echo "Path: MISMATCH"

Esperado: La habilidad está listada en el registro bajo el dominio correcto con ruta y metadatos coincidentes. El recuento total es preciso.

En caso de fallo: Si no se encuentra en el registro, reportar como BLOQUEANTE. Proporcionar la plantilla de entrada del registro:

- id: skill-name
  path: skill-name/SKILL.md
  complexity: intermediate
  language: multi
  description: Descripción en una línea

Validación

El archivo SKILL.md existe en la ruta esperada
El frontmatter YAML se analiza sin errores
Los cuatro campos obligatorios del frontmatter presentes (
```
name
```
,
```
description
```
,
```
license
```
,
```
allowed-tools
```
)
Los seis campos de metadatos presentes (
```
author
```
,
```
version
```
,
```
domain
```
,
```
complexity
```
,
```
language
```
,
```
tags
```
)
El campo
```
name
```
coincide con el nombre del directorio
La
```
description
```
tiene menos de 1024 caracteres
Las seis secciones obligatorias presentes (When to Use, Inputs, Procedure, Validation, Common Pitfalls, Related Skills)
Cada paso del procedimiento tiene los bloques Expected: y On failure:
El recuento de líneas es 500 o menos
La habilidad está listada en
```
_registry.yml
```
con el dominio, ruta y metadatos correctos
El recuento
```
total_skills
```
en el registro es preciso

Errores Comunes

Verificar el frontmatter solo con regex: El análisis YAML puede ser sutil. Un bloque multilínea
```
description: >
```
se ve diferente de
```
description: "inline"
```
. Verifique ambos patrones al buscar campos.
No encontrar la variante de la sección de validación: Algunas habilidades usan
```
## Validation Checklist
```
en lugar de
```
## Validation
```
. Ambas son aceptables; verifique cualquiera de los dos encabezados.
Olvidar el recuento total del registro: Después de añadir una habilidad al registro, el número
```
total_skills
```
en la parte superior también debe incrementarse. Este es un error común en las PRs.
Confusión entre nombre y título: El campo
```
name
```
debe estar en kebab-case coincidiendo con el nombre del directorio. El encabezado
```
# Título
```
es legible por humanos y puede diferir (p. ej., name:
```
review-skill-format
```
, título:
```
# Revisar Formato de Habilidad
```
).
El modo lenient omite bloqueantes: Incluso en modo lenient, los campos del frontmatter y las secciones obligatorias faltantes deben seguir siendo señalados. El modo lenient solo relaja las recomendaciones de estilo y metadatos.

Habilidades Relacionadas

```
create-skill
```
— La especificación de formato canónico; úsela como referencia autoritativa de cómo se ve un SKILL.md válido
```
update-skill-content
```
— Después de que pasa la validación de formato, use esto para mejorar la calidad del contenido
```
refactor-skill-structure
```
— Cuando una habilidad falla la comprobación de recuento de líneas, use esto para extraer y reorganizar
```
review-pull-request
```
— Al revisar una PR que agrega o modifica habilidades, combine la revisión de PR con la validación de formato
(Translations only) All five translation frontmatter fields present (
```
locale
```
,
```
source_locale
```
,
```
source_commit
```
,
```
translator
```
,
```
translation_date
```
)
(Translations only) Body paragraphs are in the target locale, not English
(Translations only) Code blocks are identical to the English source