菜单
Comprehensive guide for creating high-quality AI agent skills (SKILL.md files). Use when designing, drafting, reviewing, or improving skills. Covers anatomy, frontmatter, progressive disclosure, writing patterns, description optimization, supporting files, and quality checklist.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Construir la capa semántica completa de un dominio técnico end-to-end en Stratio Governance, orquestando las cinco fases del pipeline (technical terms → ontology → business views → SQL mappings → semantic terms), con publicación opcional de vistas entre mappings y semantic terms. Requiere una data collection existente — usa create-data-collection primero si no existe. Usar cuando el usuario quiera construir, completar, regenerar o auditar la capa semántica completa de un dominio, en lugar de invocar una skill de fase concreta.
Crear, ampliar o borrar clases de una ontología en Stratio Governance, con planificación interactiva a partir de ficheros de referencia (.owl/.ttl, CSVs, documentos de negocio) antes de crear. Usar cuando el usuario quiera modelar la ontología de un dominio, añadir clases a una ya existente, sembrar clases desde documentos de referencia, o eliminar clases obsoletas. Para generar las vistas de negocio a partir de la ontología, preferir create-business-views.
Crear o regenerar technical terms — descripciones de tablas y columnas — en Stratio Governance para un dominio técnico completo, y sembrar la descripción de la colección cuando falte. Usar cuando el usuario quiera documentar tablas y columnas, generar descripciones en masa para un nuevo dominio, refrescarlas tras cambios de esquema, o recuperar technical terms que falten.
Referencia de MCPs de capa semántica Stratio — reglas obligatorias, patrones de uso y buenas prácticas para las herramientas MCP de gobernanza (create_ontology, create_business_views, create_sql_mappings, create_semantic_terms, create_business_term, refine_foreign_keys, refine_semantic_foreign_keys, etc.). Cargar antes de interactuar con tools de gobernanza sin una skill dedicada, cuando haya dudas sobre el orden de invocación o los parámetros, o para refrescar las reglas de uso. Para un flujo concreto, preferir la skill create-* o refine-* correspondiente.
Build the full semantic layer of a technical domain end-to-end in Stratio Governance, orchestrating the five phases of the pipeline (technical terms → ontology → business views → SQL mappings → semantic terms), with optional view publishing between mappings and semantic terms. Requires an existing data collection — use create-data-collection first if it does not exist. Use when the user wants to build, complete, regenerate or audit the full semantic layer of a domain, rather than invoking an individual phase skill.
Create, extend or delete classes of an ontology in Stratio Governance, with interactive planning from reference files (.owl/.ttl, CSVs, business docs) before creation. Use when the user wants to model a domain ontology, add classes to an existing one, seed classes from reference documents, or remove obsolete classes. For generating the business views from the ontology, prefer create-business-views.
| name | skill-creator |
| description | Comprehensive guide for creating high-quality AI agent skills (SKILL.md files). Use when designing, drafting, reviewing, or improving skills. Covers anatomy, frontmatter, progressive disclosure, writing patterns, description optimization, supporting files, and quality checklist. |
Referencia completa para diseñar y escribir skills de alta calidad para agentes de IA. Esta guía contiene todo el conocimiento necesario para crear skills efectivas — no depende de documentación externa ni de acceso a internet.
Una skill es un conjunto de instrucciones empaquetadas como archivos Markdown que amplían las capacidades de un agente de IA. El punto de entrada es siempre un archivo llamado SKILL.md.
<skill-name>/
SKILL.md # Obligatorio — instrucciones principales
guide.md # Opcional — guía complementaria
scripts/ # Opcional — scripts auxiliares ejecutables (Python, bash)
helper.py
references/ # Opcional — documentos de referencia estáticos (esquemas, ejemplos)
schema.md
assets/ # Opcional — archivos usados en la generación de salida (plantillas, iconos)
template.html
create-quality-rules, explore-dataCreateQualityRulesexploreData/slash-command para invocar la skillContenido de referencia — Añade conocimiento que el agente aplica a su trabajo actual. Se ejecuta en línea con el contexto de la conversación. Ejemplos: convenciones de código, patrones de API, guías de estilo, conocimiento de dominio.
---
name: api-conventions
description: "REST API design patterns for this codebase. Use when writing or reviewing API endpoints."
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats using the ErrorResponse schema
- Include request validation with Zod schemas
Contenido de tarea — Instrucciones paso a paso para acciones específicas. Normalmente las invoca el usuario de forma manual. Ejemplos: despliegues, commits, flujos de generación de código.
---
name: deploy
description: "Deploy the application to production. Use when the user wants to deploy or release."
---
Deploy the application:
1. Run the test suite: `npm test`
2. Build: `npm run build`
3. Push to deployment target: `npm run deploy`
Las skills se cargan en tres capas para optimizar el uso del contexto:
| Capa | Contenido | Cuándo se carga | Coste en tokens |
|---|---|---|---|
| Metadatos | name + description del frontmatter | Siempre en memoria | ~100-200 tokens por skill |
| Cuerpo | Contenido completo del SKILL.md | Solo cuando la skill se activa | Variable (apunta a < 500 líneas) |
| Recursos | Archivos complementarios (scripts, referencias, guías) | Bajo demanda, cuando se referencian | Variable |
Este sistema evita sobrecargar el contexto con skills no utilizadas. Escribe tu skill sabiendo que su cuerpo solo se carga cuando es relevante — haz que la descripción sea lo suficientemente buena para activar la carga, y mantén el cuerpo centrado en la ejecución.
Todo SKILL.md comienza con un frontmatter YAML entre marcadores ---. El frontmatter indica al agente cuándo y cómo utilizar la skill.
| Campo | Obligatorio | Descripción |
|---|---|---|
name | Sí | Identificador único. Se convierte en el /slash-command. Debe coincidir con el nombre del directorio padre |
description | Sí (muy recomendado) | Qué hace la skill y cuándo usarla. Es el mecanismo principal de activación |
Regla de formato: Envuelve siempre el valor de description entre comillas dobles en una sola línea. Esto previene problemas de parseo YAML con caracteres especiales (dos puntos, corchetes) y asegura un frontmatter portable entre plataformas.
Anthropic, OpenCode y el plugin de GitHub Copilot Code aplican estas restricciones en runtime. Una skill que viole cualquiera de ellas no se carga — y la mayoría de herramientas de empaquetado también re-validan la longitud de la descripción en el momento del pack para que el fallo aparezca localmente en vez de al instalar.
| Campo | Restricción |
|---|---|
name | 1–64 caracteres |
name | Regex ^[a-z0-9]+(-[a-z0-9]+)*$ (minúsculas, dígitos, guiones simples) |
name | No puede contener las palabras reservadas anthropic ni claude |
name | Sin etiquetas XML/HTML |
name | Debe coincidir con el nombre del directorio padre (<name>/SKILL.md) |
description | 1–1024 caracteres (solo los primeros ~250 se muestran en el listado UI de /skills) |
description | Sin etiquetas XML/HTML |
| Nombre del fichero | Exactamente SKILL.md (case-sensitive) |
| Frontmatter | YAML válido entre marcadores --- de apertura y cierre |
Recomendación blanda: mantén el cuerpo del SKILL.md por debajo de ~500 líneas (best practice de Anthropic). Si lo superas, extrae a archivos complementarios (ver §4).
La description determina cuándo el agente carga tu skill. Los agentes tienden a sub-activar las skills, por lo que las descripciones deben ser proactivas.
Patrón: verbo de acción + qué hace + "Use when..." + palabras clave de activación
Buena descripción:
description: "Assess the current data quality coverage for a domain, table, or column. Use when the user wants to understand quality status, identify gaps, find uncovered dimensions, or check which columns need quality rules."
Mala descripción:
description: "Quality assessment tool"
La mala descripción es demasiado vaga — rara vez se activará. La buena descripción incluye palabras clave específicas ("gaps", "uncovered dimensions", "quality rules") que coinciden con lo que los usuarios realmente dicen.
Reglas de optimización:
/skills para ahorrar contextoPara la referencia completa de campos con los campos opcionales y los ejercicios de optimización de descripciones, consulta frontmatter-reference.md.
Los LLMs modernos generalizan bien cuando comprenden la razón detrás de una instrucción. En lugar de directivas rígidas, explica la motivación:
| Menos efectivo | Más efectivo |
|---|---|
ALWAYS validate the SQL | Validate the SQL before executing because a malformed query can silently return partial results, leading to incorrect analysis |
NEVER use markdown tables | Format output as flowing prose paragraphs because the response will be read aloud by text-to-speech software, which cannot pronounce table structures |
DO NOT skip profiling | Run profiling before analysis because without real data distribution knowledge, you may miss null patterns or outliers that invalidate statistical conclusions |
Este enfoque (a veces llamado "teoría de la mente") es más efectivo que las directivas en MAYÚSCULAS porque el agente puede aplicar el principio subyacente a casos límite que no ha visto antes.
## 1. Discovery, ## 2. Analysis| Intención del usuario | Acción |
|----------------------|--------|
| "Analiza el dominio X" | Flujo completo (fases 1-5) |
| "Solo muéstrame las tablas" | Saltar a la fase 1 únicamente |
Apunta a 150-200 instrucciones discretas en una skill. Por encima de este umbral, el cumplimiento del LLM tiende a disminuir. Para cada línea, pregúntate: "¿Cometería el agente un error sin esta instrucción?" Si no, elimínala.
Incluye 2-5 ejemplos realistas cuando el comportamiento esperado no sea obvio:
No hagas referencia directa a nombres de archivo específicos de plataforma como AGENTS.md, CLAUDE.md u opencode.json. Los scripts de empaquetado renombran estos archivos según la plataforma de destino. Usa frases genéricas en su lugar:
| No escribas | Escribe en su lugar |
|---|---|
| "As defined in AGENTS.md" | "As defined in the agent's instructions" |
| "Following the rules in CLAUDE.md" | "Following the agent's rules" |
| "Use the AskUserQuestion tool" | "Follow the user question convention" |
Mantén el SKILL.md por debajo de 500 líneas. Si te acercas a este límite, extrae las secciones detalladas a archivos complementarios dentro de la carpeta de la skill (ver sección 4).
Extrae contenido a un archivo separado cuando:
| Directorio | Propósito | Ejemplo |
|---|---|---|
| Raíz de la carpeta de la skill | Guías complementarias cargadas bajo demanda | advanced-guide.md, field-reference.md |
scripts/ | Scripts auxiliares que la skill invoca | scripts/validate.py, scripts/generate.sh |
references/ | Documentos de referencia estáticos (esquemas, especificaciones) | references/api-schema.json |
assets/ | Archivos usados en la generación de salida | assets/template.html, assets/logo.png |
Haz referencia a los archivos desde el SKILL.md usando rutas relativas:
For the complete field reference, see `frontmatter-reference.md`.
For writing patterns and anti-patterns, see `writing-patterns.md`.
Si una guía es compartida entre varias skills, colócala en la carpeta central de guides y declárala en un archivo de manifiesto guides dentro del directorio de la skill (un nombre de archivo por línea).
Usa la sintaxis !`command` para ejecutar comandos de shell e inyectar la salida antes de que el agente vea el contenido:
## Current environment
- Node version: !`node --version`
- Git branch: !`git branch --show-current`
Para comandos multilínea:
```!
git log --oneline -5
npm test -- --reporter=json 2>/dev/null | jq '.numPassedTests'
```
Para archivos de referencia de más de 300 líneas, incluye una tabla de contenidos al principio para que el agente pueda navegar directamente a la sección relevante.
Para el catálogo completo de patrones de escritura con ejemplos de código concretos para cada uno, consulta writing-patterns.md.
Resumen de patrones clave:
Ejecuta esta lista de verificación antes de finalizar cualquier skill:
name y description; la descripción comienza con verbo de acción e incluye "Use when..."AGENTS.md ni a CLAUDE.md — se usan frases genéricasguides/<file> o nombre de archivo directo)name ≤ 64 chars, cumple ^[a-z0-9]+(-[a-z0-9]+)*$, coincide con el nombre del directorio padre, sin palabras reservadas (anthropic/claude), sin etiquetas XMLdescription está entre comillas dobles en una sola líneadescription ≤ 1024 chars (límite duro de Anthropic / OpenCode / Copilot — las herramientas de empaquetado pueden abortar si se excede)