Pi Agent Skills: sistema de habilidades

Las Skills (habilidades) son paquetes de capacidades autocontenidos que permiten a la IA cargar bajo demanda instrucciones de flujo de trabajo y scripts de herramientas de áreas especializadas.

Pi Agent implementael estándar de Agent Skills。


¿Qué es un Skill?

Un Skill es un directorio que contieneSKILL.mdarchivos.

SKILL.md contiene el nombre, la descripción y las instrucciones detalladas de uso de la habilidad. La IA lo lee y ejecuta automáticamente cuando es necesario.

Puedes entender Skill como un «manual de entrenamiento profesional» para la IA: no ocupa espacio de contexto normalmente, se carga solo cuando es necesario.


Cómo funciona Skill

El proceso de carga completo consta de cuatro pasos; la idea central es «primero ver el directorio, luego leer el contenido completo».

  1. Al iniciarse, Pi Agent escanea todas las ubicaciones de Skills y extrae nombres y descripciones.
  2. Las descripciones de todas las Skills disponibles se incrustan en el prompt del sistema en formato XML.
  3. Cuando la tarea del usuario coincide con la descripción de una Skill, la IA carga automáticamente el SKILL.md completo con la herramienta read.
  4. La IA sigue las instrucciones en SKILL.md y usa rutas relativas para referirse a los scripts y recursos dentro del directorio de la habilidad.

Ten en cuenta que el modelo no necesariamente lee de forma proactiva; si es necesario, indícalo explícitamente en el prompt, o usa/skill:nombrepara forzar la carga.

Este diseño se llama «divulgación progresiva (Progressive Disclosure)»: solo la descripción permanece siempre en el contexto; las instrucciones completas se cargan bajo demanda.


Estructura de directorios de Skill

Solo SKILL.md es obligatorio; los demás directorios se crean según sea necesario.

my-skill/
├── SKILL.md              # 必需:Frontmatter + 指令
├── scripts/              # 辅助脚本
│   └── process.sh
├── references/           # 详细参考文档(按需加载)
│   └── api-reference.md
└── assets/
    └── template.json

Formato de SKILL.md

SKILL.md usa YAML Frontmatter para definir la metainformación, seguida del cuerpo de instrucciones en formato Markdown:

Ejemplo

---
name: my-skill
description: qué hace esta habilidad y cuándo usarla. La descripción debe ser específica y clara.
---

# My Skill

## Instalación

Ejecuta antes del primer uso:
```bash
cd ~/projects/brave-search-skill && npm install
```

## Uso

```bash
bash scripts/process.sh <input>
```

## Referencia

Ver [guía de referencia](references/api-reference.md)

Al hacer referencia a archivos dentro del directorio de la habilidad, usarutas relativas。


Campos de Frontmatter

Solo name y description son obligatorios; los demás campos se agregan según sea necesario.

CampoObligatorioDescripción
nameSíMáximo 64 caracteres; solo letras minúsculas, números y guiones. Pi Agent no requiere que el nombre coincida con el directorio padre.
descriptionSíMáximo 1024 caracteres. Describe la función de la habilidad y cuándo usarla; esta es la base para que la IA decida si cargar la habilidad.
licensenoNombre de la licencia
compatibilitynoMáximo 500 caracteres; requisitos del entorno
metadatanoPares clave-valor personalizados
allowed-toolsnoLista de herramientas preaprobadas (experimental)
disable-model-invocationnoCuando se establece en true, la Skill se oculta del prompt del sistema y solo se puede invocar manualmente mediante /skill:name.

description es el factor clave para que la IA decida si cargar tu Skill; asegúrate de que sea específica y clara.

Una description vaga puede hacer que la Skill se active en escenarios inapropiados o que se ignore en escenarios donde se necesita.


Ubicaciones de carga de Skill

Pi Agent escanea Skills en dos niveles: global y proyecto. Las reglas de descubrimiento varían ligeramente según la ubicación.

UbicaciónAlcanceReglas de carga
~/.pi/agent/skills/GlobalLos archivos .md raíz y los directorios que contienen SKILL.md se descubren recursivamente.
~/.agents/skills/GlobalLos directorios que solo contienen SKILL.md se descubren recursivamente; los archivos .md raíz se ignoran.
.pi/skills/ProyectoLos archivos .md raíz y los directorios que contienen SKILL.md se descubren recursivamente.
.agents/skills/ProyectoLos directorios que solo contienen SKILL.md se descubren recursivamente.
Pi PackagesGlobal o proyectoel directorio skills/ o la entrada pi.skills en package.json
CLIEsta ejecución actual--skill ruta se carga explícitamente; se puede pasar repetidamente.

Un apunte adicional: en ~/.agents/skills/ y .agents/skills/ del proyecto, los archivos .md anidados en subdirectorios agrupados que declaran Frontmatter válido también se reconocen, mientras que los .md en el nivel superior sin Frontmatter se ignoran.

Parámetros de CLI--no-skillsSe puede deshabilitar el descubrimiento automático de habilidades, pero las rutas--skill rutaproporcionadas explícitamente aún se cargan.


Validación y conflictos de nombres

Pi Agent valida las Skills según el estándar de Agent Skills; la mayoría de los problemas solo generan advertencias y la Skill aún se carga.

Un SKILL.md sin description no se carga; los archivos malformados también reciben solo una advertencia y no se cargan.

Cuando Skills con el mismo nombre provienen de diferentes ubicaciones, se emite una advertencia y se conserva la primera encontrada.


Comandos de Skill

Cada Skill se registra automáticamente como el comando/skill:nombre:

/skill:brave-search
/skill:pdf-tools extract

Los parámetros después del comando se agregan en la formaUser: parámetroal contenido de la Skill.

Tomando /skill:pdf-tools extract report.pdf como ejemplo, el contenido expandido es aproximadamente el siguiente:

/skill:pdf-tools extract report.pdf

User: extract report.pdf

Al recibir este contenido, la IA busca y ejecuta los scripts en el directorio scripts/ según las instrucciones de SKILL.md.

Se puede deshabilitar el registro de comandos de Skill mediante la configuración:

Ejemplo

// Ruta del archivo: ~/.pi/agent/settings.json
{
  "enableSkillCommands": false
}

También se puede, mediante la configuración,disable-model-invocationhacer que ciertas Skills solo se invoquen manualmente y no aparezcan automáticamente en el prompt del sistema.


Importar Skills desde otras herramientas

Pi Agent puede cargar Skills de Claude Code u OpenAI Codex:

Las dos configuraciones siguientes se escriben respectivamente en el settings.json global y del proyecto; ajusta las rutas según tu directorio real.

Ejemplo

// Ruta del archivo: ~/.pi/agent/settings.json (importación global)
{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

Para Skills de Claude Code a nivel de proyecto:

Ejemplo

// Ruta del archivo: .pi/settings.json (importación a nivel de proyecto)
{
  "skills": ["../.claude/skills"]
}

Las instrucciones en las Skills pueden pedir a la IA que realice cualquier operación, incluida la ejecución de archivos ejecutables.

Antes de usar Skills de terceros, se recomienda revisar su contenido.


Ejemplo completo de Skill

El siguiente es un ejemplo completo de una Skill de búsqueda web:

Ejemplo

---
name: brave-search
description: Busca en la web y extrae contenido mediante la API de Brave Search. Adecuada para buscar documentos, consultar hechos o recuperar cualquier contenido web.
---

# Brave Search

## Instalación

Instala las dependencias antes del primer uso:
```bash
cd ~/projects/brave-search-skill && npm install
```

## Búsqueda

```bash
# Ejecutar con node, no se requiere permiso de ejecución
node scripts/search.js "palabra clave" # búsqueda básica
node scripts/search.js "palabra clave" --content # incluye contenido de la página

# Si ya se le han otorgado permisos de ejecución (chmod +x scripts/search.js), también puede ejecutarlo directamente
./scripts/search.js "palabra clave de consulta"
```

## Extraer contenido de la página

```bash
node scripts/content.js https://example.com
```

Repositorios recomendados de Skills

Estos dos repositorios proporcionan una gran cantidad de Skills que se pueden usar directamente; antes de instalarlos, se recomienda leer todo el contenido.

RepositorioDirección del contenidoEscenarios aplicables
Anthropic SkillsProcesamiento de documentos (docx, pdf, pptx, xlsx), desarrollo webProcesamiento por lotes de documentos de oficina diarios, construcción de páginas front-end
Pi SkillsBúsqueda web, automatización del navegador, API de Google, transcripción de audioTareas que requieren obtención de datos en línea, operación automatizada y transcripción multimedia
Otras extensiones