Skills

Un skill es un archivo Markdown que le enseña a un agente cómo hacer algo. El super-agent carga los skills a demanda — solo los relevantes para la conversación actual. APX trae un conjunto de skills incluidos (skills/<slug>/SKILL.md en el paquete) y soporta skills personalizados con alcance de proyecto y globales de usuario.

Los skills y los agentes son independientes — un agente puede referenciar skills por slug en su frontmatter, y el super-agent los descubre automáticamente a partir de los directorios registrados.

Dónde viven los skills

El catálogo propio del super-agent (lo que carga a demanda, y lo que muestra el gestor de Skills de la web) escanea tres ubicaciones, en orden de prioridad:

1. <proyecto>/.apc/skills/<slug>/SKILL.md (o <slug>.md) — alcance de proyecto (visible solo en este proyecto)
2. ~/.apx/skills/<slug>/SKILL.md — global de usuario (todos los proyectos de esta máquina)
3. <APX package>/src/core/runtime-skills/<slug>/SKILL.md — incluido (viene con APX, inmutable, siempre disponible; source "builtin")

Gana la primera coincidencia por slug. Un skill de proyecto sobrescribe en silencio a un skill global de usuario o incluido con el mismo slug.

Nota

<APX package>/skills/<slug>/SKILL.md (la carpeta de la que leen apx skills add/sync, más abajo) es un catálogo separado, más liviano, pensado para herramientas de IDE externas — no es el set que el super-agent carga en runtime. No confundas los dos: el catálogo de runtime vive bajo src/core/runtime-skills/.

Instalar en herramientas de IDE

Ejecutar apx skills add copia (o enlaza) los skills incluidos dentro de los archivos de reglas de tu IDE, así herramientas como Claude Code, Cursor y Copilot los toman automáticamente.

# Interactivo: elegí alcance global o de proyecto
apx skills add

# Instalar en todos los dirs globales de skills (recomendado para la primera configuración)
apx skills add --global

# Instalar solo en targets específicos
apx skills add claude-code cursor

# Instalar skills con alcance de proyecto para targets específicos
apx skills add windsurf copilot

Targets de IDE

Target ID	IDE	Archivo escrito
claude-code	Claude Code	.claude/skills/apx/SKILL.md
cursor	Cursor	.cursor/rules/apx.mdc
windsurf	Windsurf	.windsurf/rules/apx.md
copilot	GitHub Copilot	.github/copilot-instructions.md (agregado al final)
trae	Trae	.trae/rules/project_rules.md (agregado al final)

Las instalaciones globales escriben en ~/.claude/skills/, ~/.cursor/skills/, ~/.codex/skills/ y ~/.agents/skills/. Estos directorios son leídos por Claude Code, Cursor, Codex (OpenAI), Antigravity y cualquier herramienta compatible con skills.sh.

Codex y Antigravity leen AGENTS.md automáticamente — no hace falta una instalación aparte para esos.

Nota

Claude Desktop no soporta archivos de proyecto. Usá el bridge apx-mcp en lugar de skills para las integraciones con Claude Desktop.

Listar y estado

# Listar los skills instalados en .apc/skills/ de este proyecto
apx skills list

# Listar el catálogo completo (proyecto + global + incluidos), con estado on/off/private
apx skills list --all

# Mostrar qué skills incluidos están presentes en cada dir global
apx skills status

apx

$ apx skills status
  Claude Code     ✓ installed       ~/.claude/skills/apx/SKILL.md
Cursor          ✓ installed       ~/.cursor/rules/apx.mdc
Windsurf        ✗ not installed   ~/.windsurf/rules/apx.md
Copilot         ✓ installed       ~/.github/copilot-instructions.md
Trae            ✗ not installed   ~/.trae/rules/apx.md

note: run apx skills add --global to install the missing targets

apx skills status mostrando los skills instalados y faltantes en los dirs globales

Sincronizar los skills incluidos

Después de actualizar APX, re-sincronizá los skills incluidos en todos los dirs globales:

apx skills sync

# Verbose — muestra cada línea (skill × target)
apx skills sync --verbose

sync es idempotente y también se ejecuta automáticamente durante npm install -g @agentprojectcontext/apx.

Gestionar skills desde el panel web

El panel web tiene un gestor de Skills al estilo Claude Desktop: una lista a la izquierda de los skills instalados más un visor a la derecha que renderiza el SKILL.md seleccionado, con un dropdown Add (crear online, subir un .zip, o importar desde un repo git) y un switch de encendido/apagado por skill.

Lo vas a encontrar en dos lugares:

• Settings → Agents → Skills (/settings/skills) — la entrada global, con un selector de scope (ver más abajo) y dos pestañas internas: Skills (el gestor) y Config (RAG) (la configuración del Skill Inspector — umbrales, estado del índice y una prueba de dry-run de un prompt).
• La pestaña Skills propia de un proyecto — el mismo gestor incrustado y fijado al scope de ese proyecto, para que puedas habilitar, deshabilitar, agregar o inspeccionar skills sin salir del proyecto.

🖥️ SCREENSHOT · web Gestor de Skills — lista de skills instalados con badges de source, y el visor de SKILL.md apx web, luego Settings → Skills (o la pestaña Skills de un proyecto)

Gestor de Skills — lista de skills instalados con badges de source, y el visor de SKILL.md

Habilitar/deshabilitar por scope

Cualquier skill (excepto los incluidos — ver abajo) se puede apagar por scope. Un scope es:

• default — la base del super-agent / sin proyecto, etiquetado “Super-agent (global)” en el selector web, o
• un proyecto específico, identificado por su ruta absoluta.

Un override explícito en scope de proyecto gana sobre un override en scope default, que a su vez gana sobre el fallback (habilitado). Apagar un skill en un proyecto no afecta a ningún otro proyecto ni a la base del super-agent, a menos que también lo apagues ahí.

apx skills list --all   # la columna STATE muestra on / off / private para el scope de este proyecto

Nota

El selector de scope (solo en la entrada global de Settings) lista “Super-agent (global)” más cada proyecto registrado. La pestaña Skills de un proyecto no tiene selector — siempre está fijada a ese proyecto.

Skills incluidos privados

Los skills que vienen del catálogo incluido propio de APX (src/core/runtime-skills/, mostrado con el badge de source “APX”) son privados: siempre activos, y nunca se pueden deshabilitar ni eliminar desde ningún scope. El gestor los muestra con un ícono de candado y el switch deshabilitado. Esto garantiza que el conocimiento propio de runtime de APX (apx-*, apc-context, docs de runtime de la CLI) esté siempre disponible sin importar qué deshabilite un usuario en otro lado. Los skills que vienen de ~/.apx/skills/ (source “Global”) o del .apc/skills/ de un proyecto (source “Project”) siempre se pueden alternar y eliminar.

La regla de los skills-siempre-sincronizados

Regla 6 de AGENTS.md: cuando cambiás comandos de la CLI, rutas del daemon, claves de config o cualquier flujo de trabajo documentado en un skill, actualizá el skills/<slug>/SKILL.md correspondiente en el mismo commit. Esto mantiene los skills exactos a medida que APX evoluciona.

Verificá los flags con apx <command> --help antes de documentarlos — no inventes subcomandos.

Escribí tu propio skill

Un skill es un archivo Markdown con frontmatter YAML:

---
name: my-skill
description: When to load this skill — write it as a trigger condition, not a summary.
---

<!-- Body: concrete, opinionated, anti-example-driven. -->

El campo description es lo que lee el modelo al decidir si llama a load_skill. Escribilo como un trigger: “Load BEFORE configuring X — covers Y and Z gotchas.”

Registrar un skill de proyecto

mkdir -p .apc/skills/my-skill
# escribí .apc/skills/my-skill/SKILL.md
apx skills list   # confirmá que aparece

No hace falta reiniciar el daemon — listSkills() re-escanea en cada llamada.

Ver también

• Capabilities — Agent Vault — plantillas de agentes reutilizables
• Concepts — Agents — cómo adjuntar skills a los agentes vía frontmatter
• Panel de administración Web — el gestor de Skills y la pestaña Skills por proyecto