Tutorial de Skills

En esencia, Skills son manuales de instrucciones que enseñan a la IA a hacer las cosas siguiendo un proceso fijo; una vez escritos, se pueden invocar repetidamente como una función.

Podemos considerar Skills comocómo hacer profesionalmente cierto tipo de tareas,empaquetado en un módulo de capacidad reutilizable y de activación automática.

Los Skills existen en forma de archivos Markdown; no ejecutan funciones, sino que, mediante una carga progresiva y bajo demanda, logran una transferencia de experiencia eficiente y reutilizable.

La mayor diferencia entre Skills y los Prompt tradicionales es: carga bajo demanda + divulgación progresiva (solo cuando es necesario se introduce el extenso SOP en el contexto, ahorrando enormemente tokens).

Elemento de comparación	Prompt normal	Mecanismo de Skills
Es necesario reescribirlo cada vez	Sí	No (solo se describe una vez)
Ocupación de longitud de contexto	Se introduce completo cada vez	Carga progresiva (solo lee el contenido completo cuando se activa)
Consistencia	Depende de la calidad del prompt de cada vez	Alta (SOP fijo + plantillas)
Reutilización	Copiar y pegar manualmente	Coincidencia automática / comando slash / uso compartido en el proyecto
Método de mantenimiento	Cada vez que cambias el prompt tienes que reenviarlo	Modificar el archivo SKILL.md, aplica a nivel global/proyecto

Por ejemplo, cuando solemos escribir artículos, antes de Skills, teníamos que repetir cada vez los siguientes pasos:

帮我总结文章 → 翻译 → 改成公众号风格 → 加标题 → 输出 Markdown

Con Skills:

Solo necesitas una frase:

使用「技术文章转公众号」Skill

La IA ejecutará automáticamente según los pasos que hayas establecido.

Imagina la IA como unbecario inteligente pero sin experiencia recién graduado：

Prompt normal= Cada vez tienes que enseñarle desde cero cómo hacer las cosas (hoy se lo enseñas, mañana tienes que volver a enseñárselo)
Rule / Memoria= Le pegas un "código de conducta de la empresa" en su puesto de trabajo (siempre vigente, pero solo controla actitud y formato)
MCP / Tools= Le instalas un montón de software y API en su computadora (puede utilizar herramientas externas, pero no sabe cuándo usarlas ni cómo combinarlas)
Skills= Le das directamente un conjunto completo de"paquete de capacitación para el puesto"(PDF + diagrama de flujo + SOP + plantillas de guiones + scripts comunes), y le dices: "cuando el jefe te pida hacer este tipo de tareas, sigue el método de esta carpeta"

Los principales clientes que actualmente pueden usar Skills:

Orden	Nombre de la herramienta	¿Uso gratuito de Skills?	Público recomendado	Ruta de almacenamiento predeterminada de las habilidades	Notas
1	Claude Code	Sí (oficial)	Todos	~/.claude/skills	Creador de estándares, ecosistema más completo
2	Cursor	Sí	El más utilizado para escribir código	~/.cursor/skills	Casi totalmente compatible con Claude Skills
3	Trae / OpenCode	Sí	Busca buena relación calidad-precio	Depende de la configuración de la herramienta	Principalmente usuarios en China
4	VS Code + complemento	Soporte parcial	Ya usan VSCode en profundidad	Configurar en la configuración del complemento	Siguiendo rápidamente
5	Coze / otras plataformas chinas	Soporte parcial	Prefieren la versión web	La plataforma incluye su propio mercado de habilidades	Algunas requieren membresía

Diferencias entre Skills y MCP:Skills se utilizan parareutilización de conocimiento, MCP se utiliza paraexpansión de capacidades。

Skills

Reutilización de conocimiento

Compartir conocimiento: experiencias, mejores prácticas, flujos de trabajo
Basado en archivos Markdown simples, cualquiera puede crearlo
Carga progresiva, alta eficiencia en el uso de tokens
No requiere servidor ni configuración de backend
Apto para Web / Desktop / CLI

MCP

Expansión de capacidades

Extensión de funciones: conectar API, bases de datos, herramientas externas
Requiere habilidades de programación y configuración del lado del servidor
Carga todas las definiciones de herramientas al inicio
Fuerte capacidad de integración con sistemas externos
Mayor consumo de tokens y complejidad

La estructura central de un Skill

El núcleo de Skills es:Una carpeta + un archivo SKILL.md。

El archivo SKILL.md contiene:

Metadatos (al menos nombre y descripción)
Instrucciones que dicen a la IA cómo completar una tarea específica

Un Skill es esencialmente un archivo Markdown (el nombre de archivo fijo es SKILL.md)

my-skill/
└── SKILL.md   （唯一必需）

Plantilla básica de SKILL.md:

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
---

# PDF 处理

## 使用场景
当需要对 PDF 文件进行操作时使用，例如：

- 提取 PDF 文本或表格数据
- 填写 PDF 表单
- 合并多个 PDF 文件

## 提取文本
- 使用 `pdfplumber` 提取文本型 PDF 内容  
- 扫描版 PDF 需配合 OCR 工具  

## 填写表单
- 读取 PDF 表单字段  
- 按输入数据填充并生成新文件

Ejemplo mínimo obligatorio:

---
name: skill-name
description: 说明该 Skill 的功能以及适用场景
---

Ejemplo con campos opcionales:

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Campo	Obligatorio	Descripción
name	Sí	Nombre del Skill, máximo 64 caracteres, solo se permiten letras minúsculas, números y`-`, y no puede`-`comenzar o terminar con
description	Sí	Descripción de la función y los escenarios de uso, máximo 1024 caracteres, no puede estar vacía
license	no	Nombre de la licencia o referencia al archivo de licencia que acompaña al Skill
compatibility	no	Descripción del entorno y dependencias (producto, paquetes del sistema, permisos de red, etc.), máximo 500 caracteres
metadata	no	Pares clave-valor personalizados para extender metadatos (como autor, versión)
allowed-tools	no	Lista de herramientas permitidas (separadas por espacios, función experimental)

Si necesitas materiales de referencia, ejemplos de referencia o scripts de ejecución, puedes usar una estructura de directorios más compleja para el Skill:

my-skill/
├── SKILL.md      # 必需：指令 + 元数据
├── scripts/      # 可选：可执行代码
├── references/   # 可选：文档资料
└── assets/       # 可选：模板、资源

Cómo funcionan los Skills

Los Skills utilizan la carga progresiva para gestionar el contexto de manera eficiente:

Descubrimiento:Al iniciar, la IA solo carga el nombre y la descripción de cada skill, conservando solo la información de identificación más básica.
Activación:Cuando una tarea coincide con la descripción de un skill, la IA carga las instrucciones completas de SKILL.md en el contexto.
Ejecución:La IA ejecuta según las instrucciones, cargando archivos de referencia o ejecutando código según sea necesario.

Este diseño mantiene la IA ágil y, a la vez, permite obtener más información cuando sea necesario.

Claude Code Skills

A continuación, usaremos Claude Code como ejemplo para crear un Skill sencillo.

Claude Code busca y carga Skills en el siguiente orden (cuanto más específica es la ubicación, mayor prioridad):

Nivel	Ruta	Alcance
Nivel empresarial	Configurado mediante la consola de administración (managed settings)	Todos los usuarios de la organización
Nivel personal	`~/.claude/skills/<skill-name>/SKILL.md`	Todos tus proyectos
Nivel de proyecto	`.claude/skills/<skill-name>/SKILL.md`	Solo el proyecto actual
Nivel de complemento	`<plugin>/skills/<skill-name>/SKILL.md`	Entornos donde el complemento está habilitado

Cada Skill es una carpeta; el nombre de la carpeta es el identificador del skill (se recomienda kebab-case: minúsculas + guiones).

Estructura mínima:

~/.claude/skills/
  └── code-comment-expert/          # 技能文件夹名
      └── SKILL.md                  # 唯一必填文件（必须全大写 + .md 小写）

Formato completo de SKILL.md:

---                                 #  YAML frontmatter 开始（顶格）
name: code-comment-expert           # 必填：技能名（也是 /slash 命令名）
description: >-                     # 必填：最关键一行！Claude 靠它判断是否加载
  为代码添加专业、清晰的中英双语注释。
  适合缺少文档、可读性差、需要分享审查的代码。
  常见触发场景：加注释、注释一下、加文档、explain this、improve readability

trigger_keywords:                   # 强烈推荐（大幅提升自动触发率）
  - 加注释
  - 注释
  - 加文档
  - explain code
  - document
  - comment this
  - readability

version: 1.0                        # 可选
author: yourname                    # 可选
---                                 # ← YAML 结束

# 这里开始是正文（Markdown）—— Claude 真正执行时的指令

你现在是「专业代码注释专家」。

## 核心原则
- 只在缺少注释或可读性明显不足处添加
- 优先使用英文 JSDoc / TSDoc 风格
- 复杂逻辑 / 非明显意图处额外加一行中文解释
- 注释精炼，每行不超过 80 字符
- 绝不修改原有逻辑

## 输出格式（严格遵守）
1. 先输出完整修改后的代码块（用 ```语言 包裹）
2. 再用 diff 形式展示只改动注释的部分
3. 最后说明加了哪些注释、理由

现在直接开始处理用户提供的代码，不要闲聊。

Estructura de archivos avanzada (recomendada cuando el skill se vuelve complejo)

Cuando el skill supera las 500–800 líneas, o necesita plantillas/scripts/materiales de referencia, se recomienda la siguiente organización:

~/.claude/skills/react-component-review/
  ├── SKILL.md                  # 核心指令 + 元数据（建议控制在 400 行内）
  │
  ├── templates/                # 常用模板（Claude 按需读取）
  │   ├── functional.tsx.md
  │   └── class-component.md
  │
  ├── examples/                 # 优秀/反例（给 Claude 看标准）
  │   ├── good.md
  │   └── anti-pattern.md
  │
  ├── references/               # 规范、规则、禁用词表
  │   ├── hooks-rules.md
  │   └── naming-convention.md
  │
  └── scripts/                  # 可执行脚本（需开启 code execution）
      ├── validate-props.py
      └── check-cycle-deps.sh

Ejemplo de referencia en SKILL.md:

Markdown需要给出标准函数组件时，参考 templates/functional.tsx.md 的结构。

如果违反 Hooks 规则，对照 references/hooks-rules.md 第 3–5 条说明。

如需校验 propTypes，可执行 scripts/validate-props.py "{代码片段}"。

Cuando Claude ve la referencia de ruta, carga el archivo correspondiente según sea necesario, en lugar de meterlo todo en el contexto de una vez, ahorrando enormemente tokens.

Tu primer Skill

Olvidemos por ahora el complejo proceso de creación, empecemos porusar un Skill ya existentepara empezar, y siente la comodidad que aporta.

Crear el directorio del Skill

Los Skills se almacenan en~/.claude/skills/(global personal) o en el directorio del proyecto bajo.claude/skills/(específico del proyecto).

En este capítulo probaremos en el directorio del proyecto; primero crea un directorio claude-test:

mkdir claude-test

Entra en ese directorio y crea el directorio y los archivos de skills:

mkdir -p .claude/skills/python-naming-standard

Escribir el archivo de configuración SKILL.md

Crea SKILL.md en el directorio; este es el cerebro del Skill y le indica a Claude cuándo usarlo.

---
name: Python 内部命名规范技能
description: 当用户要求重构、审查或编写 Python 代码时，请参考此规范。
---

## 指令
1. 所有的内部辅助函数必须以 `_internal_` 前缀命名。
2. 如果发现不符合此规则的代码，请自动提出修改建议。
3. 在执行 `claude commit` 前，必须检查此规范。

## 参考示例
- 正确：`def _internal_calculate_risk():`
- 错误：`def _calculate_risk():`

Requisitos de campos:

name: Debe usar únicamente letras minúsculas, números y guiones (máximo 64 caracteres)
description: Breve descripción del Skill y cuándo usarlo (máximo 1024 caracteres)

Una vez creado, la estructura de archivos es la siguiente:

Tu proyecto ahora debería verse así:

my-project/
├─ src/
│  └─ test.py              # 项目源码
├─ .claude/
│  ├─ skills/
│  │  └─ hello-world/
│  │     ├─ skill.md       # Skill 定义（YAML + Instructions，机器可执行）
│  │     └─ README.md      # Skill 说明（人类阅读，可选）
│  └─ config.yml           # Claude 项目级配置（可选）
├─ .gitignore
└─ README.md               # 项目整体说明

A continuación, ejecuta el siguiente comando en la terminal para iniciar Claude Code:

claude

Introduce la tarea:

Ayúdame a escribir una función que calcule el descuento del usuario.

Claude escaneará los Skills instalados, detectará que tu solicitud está relacionada con "escritura de código Python" y coincidirá con python-naming-standard.

Según los requisitos de SKILL.md, generará el siguiente código:

def _internal_get_discount(user_score):
    # 计算逻辑...
    return discount

Añadir archivos de recursos (opcional)

Además, podemos.claude/skills/añadir los siguientes directorios en:

Añade en la misma carpeta:

examples/: Almacena archivos de ejemplo.
references/: Almacena documentos de referencia.
scripts/: Almacena scripts ejecutables (por ejemplo, Python para procesar PDFs).

Luego, haz referencia a ellos en SKILL.md:

查看示例 commit：./examples/good-commit.txt
运行脚本：使用工具执行 ./scripts/process.py

Recopilación de recursos relacionados con Agent Skills

Descripción del recurso	Enlace
Portal de agregación de Skills	https://skills.sh/
Mercado de Skills (interfaz en chino)	https://skillsmp.com/zh
El mercado de Skills de Tencent	https://skillhub.tencent.com/
Sitio oficial estándar de Agent Skills	https://agentskills.io
Artículo oficial de ingeniería de Anthropic (conceptos prácticos de Agent Skills)	https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
Documentación de Agent Skills de VS Code Copilot	https://code.visualstudio.com/docs/copilot/customization/agent-skills
Repositorio oficial de Skills en GitHub de Anthropic	https://github.com/anthropics/skills
Lista seleccionada de habilidades de Claude (serie Awesome)	https://github.com/ComposioHQ/awesome-claude-skills
Colección de Skills para flujos de trabajo de automatización de desarrollo de software	https://github.com/obra/superpowers
Skill que genera Skills automáticamente (ejemplo oficial)	https://github.com/anthropics/skills/tree/main/skills/skill-creator

Skills recomendados:

Skill	Función principal	Comando de instalación
find-skills (vercel-labs)	Centro de búsqueda y recomendación de habilidades	`npx skills add vercel-labs/skills`
vercel-react-best-practices	Especificaciones de optimización de rendimiento para React / Next	`npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices`
frontend-design (anthropics)	Capacidad de diseño de UI de alta calidad	`npx skills add anthropics/skills --skill frontend-design`
web-design-guidelines	Accesibilidad web y estándares de UX	`npx skills add vercel-labs/agent-skills --skill web-design-guidelines`
remotion-best-practices	Mejores prácticas de producción de video con React	`npx skills add remotion-dev/skills --skill remotion-best-practices`
brainstorming (superpowers)	Capacidad de pensamiento estructurado y planificación	`npx skills add obra/superpowers --skill brainstorming`
agent-browser	Automatización y control del navegador	`npx skills add vercel-labs/agent-browser`
browser-use	Interacción con el navegador de alto rendimiento	`npx skills add browser-use/browser-use`
supabase-postgres-best-practices	Optimización de Supabase / PostgreSQL	`npx skills add supabase/agent-skills --skill supabase-postgres-best-practices`
azure-cost-optimization	Optimización de costos en la nube de Azure	`npx skills add microsoft/github-copilot-for-azure --skill azure-cost-optimization`
cloudflare/skills	Prácticas de Workers y computación en el borde	`npx skills add cloudflare/skills`
redis/agent-skills	Patrones avanzados y antipatrones de Redis	`npx skills add redis/agent-skills`
vercel-composition-patterns	Estándares de patrones de composición en React	`npx skills add vercel-labs/agent-skills --skill vercel-composition-patterns`
vercel-react-native-skills	Mejores prácticas oficiales de React Native	`npx skills add vercel-labs/agent-skills --skill vercel-react-native-skills`
sleek-design-mobile-apps	Guía de diseño de apps móviles modernas	`npx skills add sleekdotdesign/agent-skills --skill sleek-design-mobile-apps`
ui-skills	Prácticas de UI e interacción a nivel de diseñador	`npx skills add ibelick/ui-skills`
pdf (anthropics)	Capacidad de generación y análisis de PDF	`npx skills add anthropics/skills --skill pdf`
seo-audit	Auditoría y optimización SEO	`npx skills add coreyhaines31/marketingskills --skill seo-audit`
skill-creator	Capacidad de creación de Skills personalizados	`npx skills add anthropics/skills --skill skill-creator`
code-review-expert	Capacidad de revisión de código de nivel profesional	`npx skills add sanyuan0704/code-review-expert`

Otras extensiones

Vibe CodingHerramientas