OpenCode Skills

En OpenCode,las habilidades de agente (Skills)son un mecanismo para encapsular comportamientos reutilizables, a través deSKILL.mdla definición de archivos, lo que permite al LLMcargar y ejecutar bajo demandacapacidades específicas.

En comparación con los prompts normales, los Skills están más cerca de ser unidades de capacidad modulares que pueden reutilizarse en múltiples proyectos o equipos.

Los Skills son elsistema de plugins de capacidades de OpenCode, que eleva el comportamiento de la IA de un prompt único a módulos de capacidad reutilizables, hace que el flujo de desarrollo sea más estandarizado, componible y adecuado para sistemas de ingeniería complejos.

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

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

Mecanismo central

Los Skills, mediante la herramienta integrada,skillse gestionan; el flujo de trabajo es el siguiente:

1. Escanea los directorios de Skills locales y globales.
2. Expone la lista de Skills disponibles en el contexto.
3. El agente selecciona automáticamente el Skill según la tarea.
4. Carga el contenido de SKILL.md bajo demanda.

Este mecanismo evita cargar todas las reglas de una vez, mejorando el rendimiento y la utilización del contexto.

Estructura central de Skill

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

El archivo SKILL.md contiene:

• Metadatos (al menos deben incluir nombre y descripción)
• Instrucciones que indican a la IA cómo completar una tarea específica.

Un Skill es, en esencia, un archivo Markdown (el nombre de archivo está fijado como 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"
---

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

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 únicamente la información de identificación más básica.
• Activación:Cuando la tarea coincide con la descripción de un Skill, la IA lee 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 bajo demanda.

Este diseño mantiene la IA rápida y, al mismo tiempo, le permite obtener más información bajo demanda.

Ubicación de los archivos

Cada Skill necesita una carpeta independiente; dentro de la carpeta se coloca elSKILL.mdarchivo (nota: el nombre del archivo debe estar todo en mayúsculas). OpenCode buscará automáticamente en las siguientes seis ubicaciones:

La estructura típica de directorios del proyecto es la siguiente:

your-repo/
├── .opencode/
│   └── skills/
│       ├── git-release/
│       │   └── SKILL.md      ← 发版流程技能
│       ├── code-review/
│       │   └── SKILL.md      ← 代码审查技能
│       └── api-doc/
│           └── SKILL.md      ← API 文档编写技能
├── src/
└── package.json

Mecanismo de descubrimiento

El descubrimiento de Skills de OpenCode se divide en dos niveles:

• Skills locales del proyecto:OpenCode comienza desde el directorio de trabajo actual,recorre el árbol de directorios hacia arriba, nivel por nivel,hasta llegar a la raíz del árbol de trabajo de Git. En este proceso, recopila, en cada nivel de directorio a lo largo del camino,.opencode/skills/*/SKILL.md、.claude/skills/*/SKILL.md、.agents/skills/*/SKILL.mdtodos los archivos de Skill que coincidan.

• Skills globales:Simultáneamente, desde los directorios globales~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md、~/.agents/skills/*/SKILL.mdse cargan todos los Skills globales definidos.

Los Skills de ambos niveles se combinan y se ofrecen juntos al agente. Si un Skill local del proyecto y un Skill global tienen el mismo nombre,el Skill local del proyecto tiene prioridad.。

Escribir SKILL.md

1. Campos de Frontmatter

CadaSKILL.mdarchivo debe comenzar con frontmatter YAML (es decir,---la parte envuelta por `---`). OpenCode solo reconoce los siguientes campos; los campos desconocidos se ignorarán automáticamente:

2. Reglas de nomenclatura

nameEl valor del campo debe cumplir todas las siguientes condiciones a la vez; de lo contrario, el Skill no se cargará:

• La longitud debe ser de1 a 64 caracteres.
• Solo puede contenerletras minúsculas,ynúmeros,y las palabras pueden separarse con un único guion (--) para separar.
• No puede comenzar ni terminar con-un guion al principio o al final.
• No puede contener guiones consecutivos.--
• Debe coincidir exactamente con la carpeta que contiene esteSKILL.mddearchivo SKILL.md; el nombre de la carpeta debe ser completamente idéntico.

Expresión regular equivalente:

^[a-z0-9]+(-[a-z0-9]+)*$

Ejemplos de nombres válidos:git-release、api-doc、code-review、deploy2prod

Ejemplos de nombres no válidos:Git-Release(contiene mayúsculas),-release(comienza con-un guion),git--release（continuo--）

3. Escribir la descripción

descriptionEl contenido del campo afecta directamente a si el agente puede seleccionar e invocar correctamente la habilidad.Se recomienda que la descripción sea específica y clara, que indique qué hace la habilidad y en qué escenarios se utiliza, evitando ser demasiado general:

• ❌ Demasiado general:Ayudar a completar la tarea de lanzamiento de versión
• ✅ Específica y clara:从合并的 PR 中起草发版说明、提出版本号建议，并生成可直接使用的 gh release create 命令

4. Ejemplo completo

Cree en el proyecto.opencode/skills/git-release/SKILL.md, con el siguiente contenido:

En el Frontmatter,nameel valor debe coincidir con el nombre de la carpeta. En este ejemplo, la carpeta se llamagit-release, por lo tantonametambién debe escribirsegit-release, de lo contrario la habilidad no será reconocida.

Cómo descubren y cargan los agentes los Skills

Después de iniciar OpenCode, todas las habilidades disponibles actualmente se inyectan en formato XML enskillla descripción de la herramienta. El agente puede conocer qué habilidades están disponibles consultando la descripción de la herramienta:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
  <skill>
    <name>code-review</name>
    <description>Perform structured code reviews with consistent criteria</description>
  </skill>
</available_skills>

Cuando el agente determina que una habilidad es relevante para la tarea actual, invoca activamenteskillla herramienta para cargar elSKILL.mdcontenido completo de la habilidad:

skill({ name: "git-release" })

Una vez completada la carga, las instrucciones y la información de contexto definidas en la habilidad entran en la memoria de trabajo del agente, influyendo así en su comportamiento y salidas posteriores. La habilidad en sí no ejecuta ninguna acción automáticamente; solo proporciona contexto adicional y normas de comportamiento para el agente.

Configurar permisos de Skills

Enopencode.jsonEn la configuración, utilice elpermission.skillcampo para controlar qué habilidades puede acceder el agente; admite dos métodos de coincidencia: nombre exacto y comodines Glob:

Los efectos específicos de los tres tipos de permisos sobre las habilidades son los siguientes:

Anular permisos por agente

Diferentes agentes pueden necesitar acceder a diferentes conjuntos de habilidades. Se pueden configurar permisos por separado para cada agente, sobrescribiendo los valores predeterminados globales.

1. Configurar en el Frontmatter del agente personalizado

# 文件路径：~/.config/opencode/agents/my-agent.md
---
permission:
  skill:
    "documents-*": "allow"    # 该代理可以加载所有 documents- 开头的技能
                               # 其他技能遵循全局权限配置
---
 
You are a documentation assistant.

2. Configurar en opencode.json para los agentes integrados

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {                          // 内置代理名称
      "permission": {
        "skill": {
          "internal-*": "allow"        // plan 代理可以加载 internal- 开头的技能，
                                       // 即使全局配置中对其设置了 deny
        }
      }
    }
  }
}

Deshabilitar la herramienta de Skills

Para los agentes que no necesitan usar habilidades en absoluto, se puede deshabilitar directamenteskillla herramienta. Una vez deshabilitada,<available_skills>la lista se eliminará por completo del contexto del agente, lo que ahorra consumo de tokens y evita que el agente intente cargar cualquier habilidad.

1. Deshabilitar en el Frontmatter del agente personalizado

2. Deshabilitar en opencode.json para los agentes integrados

Solucionar problemas de carga de Skills

Si una habilidad no aparece en la lista de disponibles, revísela en el siguiente orden, punto por punto:

1. Verifique las mayúsculas y minúsculas del nombre del archivo

   SKILL.mdEl nombre del archivo debe estar completamente en mayúsculas; si se escribe comoskill.mdoSkill.mdno será reconocido.

2. Verifique la integridad del Frontmatter

   Asegúrese de queSKILL.mdal principio tenga un frontmatter YAML correcto y que contenganameydescriptionlos dos campos obligatorios. Si falta alguno de los dos, la habilidad no se cargará.

3. Confirme que el nombre de la habilidad sea único y tenga el formato correcto

   Si hay habilidades con el mismo nombre en diferentes rutas, puede haber conflictos. También verifiquenameque el campo cumpla con las reglas de nomenclatura (solo letras minúsculas y números, separados por guiones) y que coincida exactamente con el nombre de la carpeta.

4. Verifique la configuración de permisos

   Enopencode.jsondepermission.skillEn ella, las habilidades cuyo permiso sea"deny"deny estarán completamente ocultas para el agente y no aparecerán en la<available_skills>lista. Compruebe si hay reglas de comodín (como"*": "deny") que coincidan accidentalmente con esta habilidad.

Para más Skills, puede consultar:

• Tutorial de Skills:https://www.example.com/ai-agent/skills-agent.html