Habilidades

pi puede crear habilidades. Pídele que construya una para tu caso de uso.

Habilidades

Las habilidades son paquetes de capacidad autocontenidos que el agente carga bajo demanda. Una habilidad proporciona flujos de trabajo especializados, instrucciones de configuración, scripts auxiliares y documentación de referencia para tareas específicas.

Pi implementa el estándar Agent Skills, advirtiendo sobre la mayoría de violaciones pero siendo indulgente. Pi permite que los nombres de habilidades difieran de su directorio padre aunque el estándar lo prohíbe; esa regla es subóptima para directorios de habilidades compartidos entre múltiples harnesses de agentes.

Tabla de contenidos

• Ubicaciones
• Cómo funcionan las habilidades
• Comandos de habilidades
• Estructura de habilidades
• Frontmatter
• Validación
• Ejemplo
• Repositorios de habilidades

Ubicaciones

Seguridad: Las habilidades pueden instruir al modelo a realizar cualquier acción e incluir código ejecutable que el modelo invoca. Revisa el contenido de la habilidad antes de usarla.

Pi carga habilidades desde:

• Global:
  • ~/.pi/agent/skills/
  • ~/.agents/skills/
• Proyecto (solo después de que el proyecto sea de confianza):
  • .pi/skills/
  • .agents/skills/ en cwd y directorios ancestros (hasta la raíz del repo git, o raíz del sistema de archivos fuera de un repo)
• Paquetes: directorios skills/ o entradas pi.skills en package.json
• Configuración: array skills con archivos o directorios
• CLI: --skill <path> (repetible, aditivo incluso con --no-skills)

Reglas de descubrimiento:

• En ~/.pi/agent/skills/ y .pi/skills/, los archivos .md directos en la raíz se descubren como habilidades individuales
• En todas las ubicaciones de habilidades, los directorios que contienen SKILL.md se descubren recursivamente
• En ~/.agents/skills/ y .agents/skills/ del proyecto, los archivos .md en la raíz se ignoran

Desactiva el descubrimiento con --no-skills (las rutas explícitas --skill siguen cargándose).

Usar habilidades de otros harnesses

Para usar habilidades de Claude Code u OpenAI Codex, añade sus directorios a la configuración:

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

Para habilidades de Claude Code a nivel de proyecto, añade a .pi/settings.json:

{
  "skills": ["../.claude/skills"]
}

Cómo funcionan las habilidades

1. Al iniciar, pi escanea ubicaciones de habilidades y extrae nombres y descripciones
2. El prompt del sistema incluye habilidades disponibles en formato XML según la especificación
3. Cuando una tarea coincide, el agente usa read para cargar el SKILL.md completo (los modelos no siempre lo hacen; usa prompts o /skill:name para forzarlo)
4. El agente sigue las instrucciones, usando rutas relativas para referenciar scripts y recursos

Esto es divulgación progresiva: solo las descripciones están siempre en contexto; las instrucciones completas se cargan bajo demanda.

Comandos de habilidades

Las habilidades se registran como comandos /skill:name:

/skill:brave-search           # Load and execute the skill
/skill:pdf-tools extract      # Load skill with arguments

Los argumentos tras el comando se añaden al contenido de la habilidad como User: <args>.

Alterna comandos de habilidades vía /settings en modo interactivo o en settings.json:

{
  "enableSkillCommands": true
}

Estructura de habilidades

Una habilidad es un directorio con un archivo SKILL.md. Todo lo demás es libre.

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts
│   └── process.sh
├── references/           # Detailed docs loaded on-demand
│   └── api-reference.md
└── assets/
    └── template.json

Formato SKILL.md

---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

# My Skill

## Setup

Run once before first use:
```bash
cd /path/to/skill && npm install
```

## Usage

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

Usa rutas relativas desde el directorio de la habilidad:

See [the reference guide](references/REFERENCE.md) for details.

Frontmatter

Según la especificación Agent Skills:

Campo	Requerido	Descripción
name	Sí	Máx. 64 caracteres. Minúsculas a-z, 0-9, guiones. A diferencia del estándar, Pi no requiere que coincida con el directorio padre porque ese requisito es subóptimo para directorios compartidos.
description	Sí	Máx. 1024 caracteres. Qué hace la habilidad y cuándo usarla.
license	No	Nombre de licencia o referencia a archivo incluido.
compatibility	No	Máx. 500 caracteres. Requisitos del entorno.
metadata	No	Mapa clave-valor arbitrario.
allowed-tools	No	Lista delimitada por espacios de herramientas preaprobadas (experimental).
disable-model-invocation	No	Cuando es true, la habilidad se oculta del prompt del sistema. Los usuarios deben usar /skill:name.

Reglas de nombre

• 1-64 caracteres
• Solo letras minúsculas, números y guiones
• Sin guiones al inicio/final
• Sin guiones consecutivos

Pi no requiere que el nombre coincida con el directorio padre. El estándar Agent Skills sí, pero ese requisito es subóptimo para directorios compartidos entre múltiples herramientas.

Válido: pdf-processing, data-analysis, code-review Inválido: PDF-Processing, -pdf, pdf--processing

Mejores prácticas de descripción

La descripción determina cuándo el agente carga la habilidad. Sé específico.

Bueno:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.

Pobre:

description: Helps with PDFs.

Validación

Pi valida habilidades contra el estándar Agent Skills. La mayoría de problemas generan advertencias pero la habilidad sigue cargándose:

• Nombre supera 64 caracteres o contiene caracteres inválidos
• Nombre empieza/termina con guión o tiene guiones consecutivos
• Descripción supera 1024 caracteres

Los campos de frontmatter desconocidos se ignoran.

Excepción: Las habilidades sin descripción no se cargan.

Colisiones de nombre (mismo nombre en distintas ubicaciones) advierten y mantienen la primera habilidad encontrada.

Ejemplo

brave-search/
├── SKILL.md
├── search.js
└── content.js

SKILL.md:

---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
---

# Brave Search

## Setup

```bash
cd /path/to/brave-search && npm install
```

## Search

```bash
./search.js "query"              # Basic search
./search.js "query" --content    # Include page content
```

## Extract Page Content

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

Repositorios de habilidades

• Anthropic Skills - Procesamiento de documentos (docx, pdf, pptx, xlsx), desarrollo web
• Pi Skills - Búsqueda web, automatización de navegador, APIs de Google, transcripción