Las skills para agentes se parecen cada vez menos a fragmentos de prompts y más a una verdadera capa de distribución para el trabajo con IA.
Eso es una buena noticia, pero también plantea un nuevo problema para las empresas: cuando cada equipo escribe sus propios archivos SKILL.md, ¿dónde se alojan, quién los revisa, cómo los descubren las personas y cómo se evita que un flujo de trabajo útil se convierta en un riesgo invisible para la cadena de suministro?
Los directorios públicos como skills.sh ofrecen un patrón útil. Indexan skills de GitHub, proporcionan comandos de instalación, las clasifican por popularidad y facilitan que se descubran para distintos agentes. Un registro empresarial debería adoptar una estructura similar, pero añadir gobernanza: responsables, versionado, aprobación, control de acceso, telemetría y revisión de seguridad.
Este artículo propone un diseño práctico para ese espacio colaborativo.
En resumen
- Una skill suele ser una carpeta que contiene un archivo
SKILL.mdobligatorio y, de manera opcional,scripts/,references/yassets/. - Los campos
nameydescriptionno son decorativos. Son metadatos de enrutamiento que ayudan a un agente a decidir cuándo cargar la skill. - Los registros públicos como
skills.shfuncionan principalmente como capas de descubrimiento e instalación sobre skills alojadas en GitHub. - Compartir una skill pública puede ser tan sencillo como publicar un repositorio que contenga carpetas válidas con
SKILL.mdy proporcionar un comando de instalación. - Compartir skills privadas debe tratarse más como la publicación de paquetes internos que como el intercambio de prompts en un documento.
- Un registro empresarial debe admitir revisiones, responsables, versiones, destinos compatibles, registros de cambios, políticas de instalación y reversión.
- Una aplicación privada al estilo de
skills.shnecesita dos vías: una aplicación web para descubrimiento y gobernanza, y una CLI para instalar skills en proyectos locales o carpetas de agentes. - Para repositorios privados, usa un modelo de tokens de instalación de GitHub App en lugar de pedirles tokens de acceso personal a los desarrolladores.
- Instalar una skill puede significar descargarla localmente para un desarrollador o abrir un pull request que incorpore una copia al repositorio.
- Las actualizaciones de skills deben guiarse por un lockfile: registra la versión o el commit instalado, compáralo con el registro y luego abre un PR de actualización.
- Contribuir skills debería seguir un flujo normal de PR hacia el repositorio del registro, con validación, responsables y revisión de seguridad.
- Los mayores riesgos son las instrucciones desactualizadas, las descripciones imprecisas de activación, los scripts inseguros, los secretos ocultos, la inyección de prompts y las skills que solo funcionan en el entorno local de su autor original.
- Comienza con un repositorio privado de Git y un archivo de índice. Añade API, búsqueda, telemetría y flujos de aprobación solo cuando los equipos realmente estén reutilizando skills.
Qué aprenderás aquí
Al terminar, deberías poder:
- explicar cómo funciona el formato
SKILL.md - entender el modelo general detrás de directorios públicos como
skills.sh - publicar una skill de forma pública desde un repositorio de GitHub
- diseñar un registro empresarial privado de skills para agentes
- diseñar los flujos de la aplicación para instalar, actualizar y contribuir skills privadas
- entender qué papel cumple la autenticación con GitHub App
- definir un flujo de revisión de skills antes de su instalación
- crear un manifiesto de registro sencillo que tu equipo pueda mantener en Git
- identificar las brechas de gobernanza antes de que un ecosistema de skills crezca demasiado rápido
La estructura que deduje para el artículo
Tu prompt de investigación apunta a tres preguntas relacionadas:
- ¿Cómo funcionan los directorios públicos de skills?
- ¿Cómo se comparten skills de forma pública o privada?
- ¿Cómo podría una empresa crear un espacio colaborativo para skills sin que se vuelva un caos?
Por eso, el artículo sigue este recorrido:
SKILL.md format
|
v
Public discovery model: skills.sh and similar directories
|
v
Public publishing: GitHub repo + install command
|
v
Private sharing: internal repo or registry
|
v
Company operating model: review, ownership, security, telemetryEl público previsto son ingenieros, PMs, equipos de experiencia de desarrollo, equipos de plataforma y líderes de adopción de IA que necesitan un modelo compartido y práctico, no otra explicación de «¿qué es un prompt?».
¿Qué es una skill?
En el ecosistema actual de agentes, una skill es un pequeño paquete de conocimiento procedimental.
La versión mínima útil se ve así:
my-skill/
|-- SKILL.md
|-- references/ optional docs loaded only when needed
|-- scripts/ optional executable helpers
`-- assets/ optional templates, examples, or filesEl archivo SKILL.md suele tener dos partes:
---
name: api-contract-review
description: Review an API change for backward compatibility, schema drift, error semantics, pagination, auth, and rollout risk. Use when asked to review an API design, OpenAPI diff, or service contract.
---
# API Contract Review
Review the proposed API change in this order:
1. Identify added, changed, and removed fields.
2. Check whether old clients can keep working.
3. Compare error codes and auth requirements.
4. Inspect examples and OpenAPI files if present.
5. Return risks, required tests, and rollout notes.
If the repository has OpenAPI specs, inspect them before asking the user.Esa description es especialmente importante. La explicación pública de Anthropic sobre Agent Skills describe un modelo de divulgación progresiva: los agentes pueden comenzar con metadatos concisos y cargar la skill completa solo cuando la tarea parezca relevante. La documentación de GitHub sobre skills para Copilot también deja clara la misma estructura básica: SKILL.md usa frontmatter YAML con name y description obligatorios, seguido de instrucciones en Markdown y archivos de apoyo opcionales.
En pocas palabras: la descripción es la puerta de entrada a la skill.
Si es demasiado vaga, es posible que el agente nunca la use. Si es demasiado amplia, el agente podría usarla en el momento equivocado.
Cómo funcionan los directorios públicos de skills
El ecosistema público todavía es joven, pero el patrón empieza a quedar claro.
skills.sh describe las skills como capacidades reutilizables para agentes de IA y ofrece un flujo de instalación del tipo npx skills add owner/repo. Su documentación también explica que la clasificación se basa en telemetría anónima de la CLI y que los usuarios deben revisar las skills antes de instalarlas.
SkillsGate describe su capa de descubrimiento público como impulsada por skills.sh, al que presenta como un índice abierto de skills de GitHub. Por su parte, el repositorio público openai/skills de OpenAI muestra cómo instalar skills de Codex desde carpetas seleccionadas o experimentales mediante $skill-installer, incluidas URLs directas a directorios de GitHub.
En términos generales, el modelo público se ve así:
Author publishes skill repo on GitHub
|
v
Directory indexes SKILL.md files and repo metadata
|
v
Human or agent searches the directory
|
v
Installer fetches selected skill from source repo
|
v
Skill lands in the target agent's local skills folderEsto se parece más a una capa de descubrimiento de paquetes que a una tienda de aplicaciones tradicional. El registro puede mostrar búsqueda, clasificaciones, cantidades de instalaciones, insignias y metadatos, pero la fuente de verdad suele seguir siendo un repositorio de Git.
Esa arquitectura tiene una propiedad atractiva: publicar es fácil. Si tu repositorio es público y está estructurado correctamente, un directorio puede indexarlo.
También tiene una propiedad peligrosa: instalar es fácil.
Una skill puede contener instrucciones que influyen en el comportamiento de un agente. También puede incluir scripts. Eso significa que los equipos deben revisar las skills provenientes de registros con la misma seriedad que aplican a las dependencias de terceros.
Compartir públicamente: el camino sencillo
Si quieres compartir una skill pública, comienza con un repositorio de GitHub sin complicaciones. Aquí, lo simple es excelente.
agent-skills/
|-- README.md
|-- skills/
| |-- api-contract-review/
| | `-- SKILL.md
| |-- incident-brief/
| | |-- SKILL.md
| | `-- references/
| | `-- severity-model.md
| `-- sprint-risk-review/
| `-- SKILL.md
`-- LICENSETu README debería responder:
- ¿Qué skills incluye?
- ¿Con qué agentes las has probado?
- ¿Cómo se instala una skill?
- ¿Qué permisos o herramientas necesita cada skill?
- ¿Qué licencia se aplica?
- ¿Cómo deben reportarse los problemas?
Ejemplos de comandos de instalación:
# Install from a repo with the public skills CLI
npx skills add your-org/agent-skills --skill api-contract-review
# Install a Codex skill from a GitHub folder
$skill-installer install https://github.com/your-org/agent-skills/tree/main/skills/api-contract-reviewEn el caso de las skills públicas, la propia skill también sirve para darla a conocer. Facilita su inspección. Mantén las instrucciones legibles. Expón los supuestos peligrosos. No ocultes comportamientos críticos en un script con un nombre ingenioso.
Compartir de forma privada: la versión empresarial
Dentro de una empresa, el objetivo cambia.
No solo buscas que una skill sea fácil de descubrir. Buscas que sea confiable, reutilizable y fácil de mantener entre equipos.
El registro privado más sencillo es simplemente un repositorio privado de Git:
company-agent-skills/
|-- registry.yaml
|-- skills/
| |-- frontend-accessibility-review/
| | |-- SKILL.md
| | `-- references/
| | `-- design-system-rules.md
| |-- billing-migration-plan/
| | |-- SKILL.md
| | `-- references/
| | `-- billing-risk-checklist.md
| `-- incident-postmortem/
| |-- SKILL.md
| `-- assets/
| `-- postmortem-template.md
`-- scripts/
`-- validate-skills.tsLuego, registry.yaml se convierte en el primer catálogo compartido:
skills:
- name: frontend-accessibility-review
path: skills/frontend-accessibility-review
owner: design-platform
version: 1.4.0
status: approved
visibility: company
agents:
- codex
- claude-code
- github-copilot
permissions:
network: false
shell: false
writes_files: false
tags:
- frontend
- accessibility
- design-system
- name: billing-migration-plan
path: skills/billing-migration-plan
owner: payments-platform
version: 0.9.0
status: pilot
visibility: payments-org
agents:
- codex
- claude-code
permissions:
network: false
shell: false
writes_files: true
tags:
- billing
- migration
- risk-reviewEse archivo no tiene nada sofisticado. Esa es la idea. Les da a PMs, ingenieros, revisores de seguridad y líderes de adopción un lugar común para hablar de lo que existe.
Una arquitectura práctica para un registro empresarial
Puedes construir el registro por capas.
Layer 1: Git source of truth
skills/, registry.yaml, CODEOWNERS, PR review
Layer 2: Validation
frontmatter checks, broken link checks, dangerous pattern checks
Layer 3: Discovery
generated docs site, search index, tags, owners, examples
Layer 4: Installation
CLI command, internal package, symlink/copy into agent folders
Layer 5: Governance
approvals, versions, changelog, deprecation, telemetry, rollbackNo necesitas las cinco capas desde el primer día.
La mayoría de las empresas deberían comenzar con las capas 1 y 2. Una vez que algunos equipos realmente estén usando skills compartidas, construye la capa de descubrimiento. Cuando funcione, añade la automatización de la instalación. La gobernanza se vuelve mucho más sencilla cuando el registro ya cuenta con responsables, versiones y campos de estado.
Cómo construir la aplicación privada de skills
Ahora concretemos la aplicación.
Piensa en el registro privado como una versión interna de skills.sh, pero con los límites de confianza propios de la empresa:
+---------------------------+
| Private Skills Web App |
| search, approve, install |
+-------------+-------------+
|
v
+----------------+ +-------+--------+ +-------------------+
| GitHub OAuth | --> | Registry API | --> | GitHub App |
| user identity | | policy + index | | repo operations |
+----------------+ +-------+--------+ +---------+---------+
| |
v v
+-------+--------+ +--------+----------+
| Registry DB | | Registry Repo |
| metadata/cache | | skills/ + PRs |
+----------------+ +-------------------+
|
v
+-------+--------+
| Skills CLI |
| install/update |
+----------------+La separación importante es esta:
- La aplicación web ayuda a las personas a descubrir, revisar, aprobar y solicitar instalaciones.
- El repositorio del registro sigue siendo la fuente de verdad del contenido de las skills.
- La base de datos almacena metadatos consultables, eventos de instalación, responsables, aprobaciones y versiones en caché.
- La GitHub App realiza operaciones sobre repositorios sin que cada desarrollador tenga que crear un token personal.
- La CLI instala skills en carpetas locales porque la aplicación web no puede escribir de forma segura en la máquina de un desarrollador.
Puedes construir esto con un stack muy común:
Frontend: Next.js, Astro, Remix, or your internal platform
Backend: Node.js, Go, Python, or Rails
Database: Postgres
Search: Postgres full-text first, OpenSearch later if needed
Queue: SQS, Cloud Tasks, Sidekiq, or BullMQ
Source control: GitHub private repo
Auth: GitHub OAuth or company SSO
Repo access: GitHub App installation tokens
CLI: Node.js package, Go binary, or Python packageNo comiences con un marketplace. Comienza con un catálogo interno útil que pueda instalar de forma segura una skill aprobada.
Las principales interfaces del producto
La aplicación privada necesita cuatro pantallas principales.
Browse
search, filter, compare, read SKILL.md
Skill Detail
install commands, supported agents, owner, version, permissions
Contribute
create or edit skill, validate, open PR
Admin
approvals, repo installations, owners, policies, audit logLa página de detalle de una skill debe mostrar suficiente información para que un desarrollador o PM pueda decidir si es segura y útil:
api-contract-review
Owner: platform-api
Status: approved
Version: 1.4.2
Source: github.com/acme/company-agent-skills/skills/api-contract-review
Supported agents: codex, claude-code, github-copilot
Permissions: no shell, no network, no file writes
Last reviewed: 2026-06-09
Install locally:
skillhub install api-contract-review --agent codex
Install into repo:
skillhub repo install acme/payments-api api-contract-review --path .agents/skills
Update:
skillhub update api-contract-reviewEsa página también debe mostrar el contenido real de SKILL.md, no solo metadatos promocionales. Las skills solo son confiables si las personas pueden inspeccionarlas.
Modelo de autenticación con GitHub App
Para una aplicación empresarial, evita pedirles a los usuarios que peguen tokens de acceso personal en tu registro.
Usa dos identidades en su lugar:
GitHub OAuth user token
Who is this person?
Which org/team/repo should they be allowed to see?
GitHub App installation token
What repositories can the app read or write?
Which installation granted access?La GitHub App se instala en la organización de la empresa o en repositorios seleccionados. La documentación de REST de GitHub muestra objetos de instalación que incluyen la selección de repositorios, los permisos y una access_tokens_url. Los endpoints de contenido de repositorios y pull requests admiten tokens de acceso de instalación de GitHub App, pero el token necesita los permisos adecuados.
Para un registro privado de skills, estos son los permisos prácticos:
Repository metadata: read
Repository contents: read
Repository contents: write only if the app opens install/update PRs
Pull requests: read
Pull requests: write only if the app opens contribution/install PRsUsa el conjunto mínimo que admita el flujo que elijas.
Si la aplicación solo permite que los desarrolladores descarguen skills localmente, es posible que solo necesite acceso de lectura al repositorio del registro. Si abre pull requests para instalar skills en repositorios de productos, necesita acceso de escritura al contenido y a los pull requests de esos repositorios de destino.
Almacena lo siguiente:
installation_id
account/org id
selected repositories
granted permissionsNo almacenes tokens de acceso de instalación de larga duración. Genéralos cuando los necesites, úsalos y deja que expiren. Los tokens de instalación de GitHub son de corta duración, justo lo que necesitas para este tipo de aplicación.
Reglas de acceso a los repositorios
La aplicación necesita una respuesta clara a una pregunta engañosamente sencilla:
¿Quién puede instalar qué skill en qué repositorio?
Usa una regla de tres partes:
User identity
The person is a member of the company org or allowed team.
Skill visibility
The skill is visible to the user's org, team, or repo.
Target repo permission
The GitHub App is installed on the target repo and the user is allowed
to request changes for that repo.Esto te da un comportamiento predecible:
Can read registry repo? yes
Can see this skill? yes
Can write target repo? no
Result: show install locally, but create repo PR is disabled
Can read registry repo? yes
Can see this skill? yes
Can write target repo? yes
Result: allow repo install PRNo equipares «puede abrir la aplicación» con «puede instalar en cualquier repositorio». Ese atajo parece conveniente hasta que alguien instala una skill experimental de migración de bases de datos en un servicio de producción.
Modelo de datos del registro
Mantén el contenido de las skills en Git. Mantén los datos de búsqueda y operación en Postgres.
create table skills (
id uuid primary key,
slug text unique not null,
name text not null,
description text not null,
owner_team text not null,
status text not null,
visibility text not null,
source_repo text not null,
source_path text not null,
current_version text not null,
current_commit_sha text not null,
created_at timestamptz not null,
updated_at timestamptz not null
);
create table skill_versions (
id uuid primary key,
skill_id uuid not null references skills(id),
version text not null,
commit_sha text not null,
content_sha256 text not null,
changelog text,
validation_status text not null,
created_at timestamptz not null
);
create table skill_permissions (
skill_id uuid not null references skills(id),
permission text not null,
value text not null,
primary key (skill_id, permission)
);
create table installations (
id uuid primary key,
skill_id uuid not null references skills(id),
version text not null,
target_type text not null,
target_repo text,
target_agent text not null,
target_path text not null,
installed_by text not null,
installed_at timestamptz not null
);
create table contribution_requests (
id uuid primary key,
skill_id uuid references skills(id),
title text not null,
author text not null,
source_branch text not null,
pull_request_url text,
status text not null,
created_at timestamptz not null
);El content_sha256 es importante. Te permite responder:
- ¿Qué contenido exacto de la skill se instaló?
- ¿Una copia local se desvió de la versión aprobada en el registro?
- ¿Podemos volver a una versión conocida que funciona correctamente?
- ¿Alguien cambió la skill sin incrementar la versión?
Diseño de la API del registro
Al principio, mantén la API pequeña.
GET /api/skills
Search approved skills visible to the current user.
GET /api/skills/:slug
Return metadata, versions, rendered README/SKILL.md, and install options.
GET /api/skills/:slug/download?version=1.4.2
Return a tarball or zip of the skill folder.
POST /api/skills/:slug/install-local-token
Create a short-lived download token for the CLI.
POST /api/repos/:owner/:repo/install
Open a PR that vendors a skill into the target repo.
POST /api/repos/:owner/:repo/update
Open a PR that updates installed skills based on the lockfile.
POST /api/contributions
Create a branch and PR for a new or edited skill.
POST /api/webhooks/github
Receive push, pull_request, installation, and installation_repositories events.El endpoint de instalación local no debe devolver tokens privados de GitHub al navegador. Dale a la CLI un token de corta duración del registro y deja que el backend obtenga el contenido de GitHub y transmita el paquete.
Flujo de instalación 1: instalación local para desarrolladores
La instalación local significa: «Coloca esta skill en mi máquina o en esta copia de trabajo».
Developer runs CLI
|
v
CLI opens browser login or uses device code
|
v
Registry checks user, org, skill visibility
|
v
Registry fetches skill folder from private GitHub repo
|
v
CLI validates SKILL.md and writes target folder
|
v
CLI records lockfile entryEjemplo:
skillhub login
skillhub install api-contract-review --agent codex --scope projectResultado:
.agents/
`-- skills/
`-- api-contract-review/
`-- SKILL.md
.skillhub.lock.jsonLockfile:
{
"skills": {
"api-contract-review": {
"version": "1.4.2",
"source": "github.com/acme/company-agent-skills",
"path": "skills/api-contract-review",
"commit": "4c1b2f7",
"contentSha256": "7a4f..."
}
}
}El lockfile marca la diferencia entre «copié un prompt una vez» y «este repositorio usa intencionalmente la versión 1.4.2 de una skill revisada».
Flujo de instalación 2: instalación en el repositorio mediante pull request
La instalación en el repositorio significa: «Haz que esta skill forme parte del repositorio para que todos la tengan».
User clicks Install into repo
|
v
App checks user + target repo permissions
|
v
App creates branch in target repo
|
v
App copies skill folder into .agents/skills/<skill>
|
v
App writes or updates .skillhub.lock.json
|
v
App opens pull request
|
v
Repo owners review and mergeEl PR generado debe ser simple y auditable:
Title: Install api-contract-review skill
Files:
.agents/skills/api-contract-review/SKILL.md
.skillhub.lock.json
PR body:
Skill: api-contract-review
Version: 1.4.2
Source commit: 4c1b2f7
Permissions: no shell, no network, no file writes
Registry page: https://skills.acme.dev/skills/api-contract-reviewUsa PRs al repositorio para skills compartidas por el equipo. Usa la instalación local para skills personales o experimentos.
Flujo de actualización
La actualización de skills es donde muchos registros internos empiezan a descuidarse.
No sobrescribas archivos silenciosamente. Compara el lockfile con el registro y haz visible la actualización:
Scheduled job or user request
|
v
Read .skillhub.lock.json from target repo
|
v
Compare installed versions with approved registry versions
|
v
Generate diff and changelog
|
v
Open update PR
|
v
Run skill validation in target repoEjemplo de CLI:
skillhub outdated
skillhub update api-contract-review
skillhub repo update acme/payments-api --open-prEjemplo de PR de actualización:
Title: Update api-contract-review skill to 1.5.0
Changes:
- Narrows trigger description to OpenAPI and REST API reviews
- Adds pagination compatibility checklist
- Removes stale reference to legacy gateway
Validation:
- SKILL.md frontmatter valid
- No dangerous patterns detected
- Lockfile content hash updatedEsto importa porque las skills son instrucciones operativas. Una actualización de una skill puede cambiar cómo los agentes revisan código, escriben planes de migración o interactúan con sistemas de producción. Trátala como un cambio real.
Flujo de contribución
Contribuir una skill debería sentirse como contribuir código.
Contributor opens app
|
v
Chooses "New skill" or "Improve skill"
|
v
App provides template and validation feedback
|
v
Contributor submits
|
v
App creates branch in registry repo
|
v
App opens PR with generated checklist
|
v
Owners and security reviewers approve
|
v
Merge updates registry indexUna plantilla para una skill nueva debería solicitar:
Name
Trigger description
Owner team
Supported agents
Expected inputs
Expected outputs
Required tools
Required permissions
Example good output
Known failure modes
ReferencesEl SKILL.md generado debería partir de un enfoque conservador:
---
name: release-risk-review
description: Review a planned software release for rollout, customer impact, dependencies, observability, rollback, and communication risk. Use when asked to assess release readiness or create a release risk summary.
---
# Release Risk Review
Start by identifying the release scope, affected users, dependencies,
data migrations, operational risks, and rollback plan.
Do not approve the release. Produce a risk summary and unresolved questions.La lista de verificación del PR debería formar parte del flujo:
## Skill Review
- [ ] Description clearly says when to use the skill
- [ ] Instructions are portable across repositories
- [ ] No secrets, tokens, or internal credentials
- [ ] Scripts are necessary and reviewed
- [ ] Permissions are declared
- [ ] Example output included
- [ ] Owner team assigned
- [ ] Rollback or deprecation plan documentedEstructura de la CLI interna
La CLI es la parte con la que los desarrolladores interactuarán todos los días.
Mantén los comandos predecibles:
skillhub login
skillhub search api
skillhub show api-contract-review
skillhub install api-contract-review --agent codex
skillhub install api-contract-review --agent claude-code --global
skillhub list
skillhub outdated
skillhub update
skillhub remove api-contract-reviewPara operaciones sobre repositorios:
skillhub repo list acme/payments-api
skillhub repo install acme/payments-api api-contract-review --open-pr
skillhub repo update acme/payments-api --open-pr
skillhub repo audit acme/payments-apiLa CLI debería admitir al menos estas asignaciones de destinos:
agents:
codex:
project: ".agents/skills"
global: "~/.codex/skills"
claude-code:
project: ".claude/skills"
global: "~/.claude/skills"
github-copilot:
project: ".github/skills"
global: "~/.copilot/skills"En caso de duda, prefiere la instalación en el proyecto para flujos de equipo y la instalación global para flujos personales.
Webhooks e indexación
El registro debe actualizarse a partir de eventos de GitHub.
push to main
Re-index registry.yaml and skills/**/SKILL.md
Recompute content hashes
Update search index
Mark approved versions available
pull_request opened
Run validation
Comment with skill quality report
Request owner/security review
pull_request merged
Publish new version
Notify subscribers
installation_repositories changed
Refresh accessible repo list
Update install availabilityEsto te da un ciclo operativo útil:
Git remains source of truth
Web app remains discovery layer
CI remains quality gate
CLI remains installation layerPlan de construcción del MVP
Si estuviera construyendo esto dentro de una empresa, lo entregaría en seis versiones pequeñas.
Versión 1: catálogo de solo lectura.
Private registry repo
registry.yaml
Skill parser
Search page
Skill detail pageVersión 2: validación y revisión.
CI checks for SKILL.md
Dangerous-pattern scanner
CODEOWNERS
PR template
Status: draft, pilot, approved, deprecatedVersión 3: instalación local mediante CLI.
GitHub OAuth login
Short-lived download token
skillhub install
Target agent folder mapping
.skillhub.lock.jsonVersión 4: PRs de instalación en repositorios.
GitHub App installation
Repo picker
Branch creation
Copy skill folder
Open pull requestVersión 5: automatización de actualizaciones.
Outdated skill detection
Changelog rendering
Update PRs
Subscription notificationsVersión 6: flujo de contribución.
New skill form
Edit skill form
Generated branch and PR
Validation comments
Approval dashboardEste camino permite que el registro sea útil antes de volverse sofisticado.
El flujo de revisión
La revisión de una skill debe combinar revisión de producto, de ingeniería y de seguridad.
Este es un flujo ligero:
Author opens PR with SKILL.md
|
v
CI validates structure and metadata
|
v
Owner reviews usefulness and scope
|
v
Security reviews scripts, tools, secrets, and prompts
|
v
Pilot group installs pinned version
|
v
Registry marks skill approvedLa lista de verificación para la revisión debe preguntar:
- ¿La
descriptionindica claramente cuándo usar la skill? - ¿La skill tiene un alcance lo suficientemente acotado para ser confiable?
- ¿Depende de rutas locales, chats privados o de la máquina de una sola persona?
- ¿Los scripts son legibles, mínimos y necesarios?
- ¿Le pide al agente que ignore instrucciones de mayor prioridad?
- ¿Recopila o expone secretos?
- ¿Escribe archivos, realiza llamadas de red o ejecuta comandos de shell?
- ¿Incluye ejemplos de buenos resultados?
- ¿Hay una persona responsable de mantenerla?
La literatura de investigación ya nos advierte dónde se complica esto. Un artículo de OpenReview de 2026 que analizó 138,133 archivos públicos de SKILL.md encontró que las skills públicas suelen tener defectos de reutilización relacionados con el enrutamiento, la portabilidad, la organización de recursos y la seguridad del comportamiento. Un artículo de arXiv de 2026 sobre ataques semánticos a la cadena de suministro encontró que el descubrimiento y la selección de skills en un registro pueden manipularse mediante descripciones adversarias. Otro artículo de 2026, SkillGuard, sostiene que los ecosistemas de skills necesitan una gobernanza consciente de los permisos porque la revisión estática por sí sola no conecta por completo la intención declarada de una skill con su comportamiento en tiempo de ejecución.
Para el trabajo en una empresa, eso significa que el registro no debe quedarse en «¿se puede interpretar el YAML?».
Un script mínimo de validación de skills
Puedes comenzar con un pequeño script de validación en CI. Este ejemplo es intencionalmente modesto:
import fs from "node:fs";
import path from "node:path";
import YAML from "yaml";
const root = process.argv[2] ?? "skills";
const required = ["name", "description"];
const dangerousPatterns = [
/ignore (all )?(previous|prior) instructions/i,
/do not tell the user/i,
/rm -rf/i,
/curl .* \| *sh/i,
/-----BEGIN (RSA |OPENSSH |EC )?PRIVATE KEY-----/i,
];
function walk(dir: string): string[] {
return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
const full = path.join(dir, entry.name);
return entry.isDirectory() ? walk(full) : [full];
});
}
const skillFiles = walk(root).filter((file) => file.endsWith("SKILL.md"));
let failures = 0;
for (const file of skillFiles) {
const text = fs.readFileSync(file, "utf8");
const match = text.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
if (!match) {
console.error(`${file}: missing YAML frontmatter`);
failures++;
continue;
}
const frontmatter = YAML.parse(match[1]);
for (const field of required) {
if (!frontmatter?.[field]) {
console.error(`${file}: missing ${field}`);
failures++;
}
}
if (!/^[a-z0-9-]+$/.test(frontmatter.name ?? "")) {
console.error(`${file}: name must be lowercase kebab-case`);
failures++;
}
if ((frontmatter.description ?? "").length < 40) {
console.error(`${file}: description is probably too vague`);
failures++;
}
for (const pattern of dangerousPatterns) {
if (pattern.test(text)) {
console.error(`${file}: matched dangerous pattern ${pattern}`);
failures++;
}
}
}
if (failures > 0) {
process.exit(1);
}Esto no hace que una skill sea segura. Detecta los errores obvios para que los revisores puedan concentrarse en aplicar su criterio.
Destinos de instalación
Los distintos agentes esperan encontrar skills en lugares diferentes. La documentación pública de GitHub Copilot menciona directorios de skills de proyecto como .github/skills, .claude/skills o .agents/skills, y directorios de skills personales como ~/.copilot/skills o ~/.agents/skills.
En la práctica, una empresa debería definir una fuente interna canónica e instalar desde ahí para los agentes de destino:
company-agent-skills repo
|
+--> .agents/skills/ shared project convention
|
+--> .claude/skills/ Claude Code convention
|
+--> .github/skills/ GitHub Copilot project convention
|
+--> ~/.codex/skills/ personal Codex installationPara un proyecto, prefiere skills del proyecto incorporadas al repositorio cuando el flujo de trabajo forme parte de cómo ese repositorio debe construirse u operarse.
Para una persona, prefiere skills globales cuando el flujo de trabajo pertenezca al individuo, como la toma de notas personales, el estilo de escritura o la automatización local.
Para una empresa, prefiere skills administradas por el registro cuando el flujo de trabajo deba compartirse, revisarse, versionarse y poder descubrirse.
Decisiones sobre registros públicos y privados
Esta es una tabla sencilla para tomar la decisión:
| Pregunta | Skill pública | Skill empresarial privada |
|---|---|---|
| ¿Revela procesos internos? | No | Tal vez |
| ¿Menciona sistemas privados? | No | Sí |
| ¿Pueden beneficiarse usuarios externos? | Sí | Por lo general, no |
| ¿Necesita aprobación de la empresa? | Opcional | Sí |
| ¿Necesita control de acceso? | No | Sí |
| ¿Necesita telemetría interna? | Deseable | Importante |
| Tipo de revisión | Revisión de mantenedores de código abierto | Producto, ingeniería y seguridad |
| Fuente de instalación | GitHub público o registro público | Git privado, CLI interna, registro de paquetes |
Una buena skill pública enseña un flujo de trabajo general.
Una buena skill privada codifica el conocimiento operativo real de la empresa.
Por ejemplo, incident-postmortem podría ser pública si enseña un formato genérico de revisión de incidentes. Se vuelve privada cuando incluye tus niveles de severidad, rutas de escalamiento para el equipo de guardia, reglas internas de la página de estado y plantillas de comunicación con clientes.
Qué les debe importar a los PMs
Los PMs no necesitan mantener el registro, pero sí deben prestar mucha atención a lo que se incluye en él.
Las skills pueden codificar criterios de producto:
- cómo escribir un plan de lanzamiento
- cómo revisar migraciones que afectan a los clientes
- cómo preparar una nota de lanzamiento
- cómo evaluar temas recurrentes en los tickets de soporte
- cómo convertir notas de descubrimiento en criterios de aceptación
- cómo decidir si una funcionalidad necesita un lanzamiento gradual
El registro se convierte en una capa de memoria sobre cómo prefiere trabajar la empresa.
Eso es poderoso. También es la razón por la que las skills deben ser legibles para quienes no las escribieron. Si un PM no puede entender el flujo de trabajo al leer SKILL.md, probablemente la skill depende de demasiada magia.
El modelo operativo
Un registro empresarial saludable tiene unas cuantas reglas sencillas:
- Cada skill tiene una persona responsable.
- Cada skill aprobada tiene una versión.
- Cada skill de riesgo tiene permisos documentados.
- Cada script tiene una razón para existir.
- Cada comando de instalación permite fijar una versión o un commit.
- Cada skill obsoleta tiene un reemplazo o una fecha de eliminación.
- Cada skill crítica para la empresa tiene ejemplos y pruebas.
El registro debería exponer esto como metadatos:
name: incident-postmortem
owner: sre-platform
version: 2.1.0
status: approved
risk: medium
requires_review_from:
- sre-platform
- security
tested_agents:
- codex
- claude-code
- github-copilot
last_reviewed: "2026-06-09"Puedes mostrar los metadatos en un pequeño sitio interno:
Skill Owner Status Agents
-------------------- --------------- --------- -------------------------
incident-postmortem sre-platform approved codex, claude-code
api-contract-review platform-api approved codex, copilot
billing-migration payments pilot codexEste es el espacio colaborativo: no un hilo de chat lleno de prompts ingeniosos, sino un catálogo visible de conocimiento operativo revisado.
Plan de adopción recomendado
Comienza poco a poco.
Fase 1: recopila las skills que ya existen.
Find local SKILL.md files
Normalize names and descriptions
Move shared candidates into a private repo
Add CODEOWNERS
Add CI validationFase 2: publica el catálogo interno.
Generate registry.yaml
Create a searchable docs page
Add examples and install commands
Mark skills as draft, pilot, approved, or deprecatedFase 3: automatiza la instalación.
Build a small internal CLI
Support install by name and version
Write into .agents/skills or agent-specific directories
Record anonymous install eventsFase 4: añade gobernanza.
Require owner approval
Require security review for scripts or network access
Support rollback to previous versions
Track usage, stale skills, and failed activationsEste es el flujo del estado final:
Team authors skill
|
v
Pull request validates and reviews it
|
v
Registry publishes approved version
|
v
Developers install it into project or global agent folders
|
v
Usage and feedback create the next improvement PRBrechas a tener en cuenta
El ecosistema de skills avanza rápidamente y algunas brechas siguen sin resolverse.
Primero, la compatibilidad entre agentes sigue siendo desigual. La estructura de SKILL.md es portable, pero distintos agentes pueden admitir diferentes directorios, permisos de herramientas, flujos de instalación y comportamientos en tiempo de ejecución.
Segundo, las señales de calidad son inmaduras. Las estrellas, las cantidades de instalaciones y la popularidad ayudan al descubrimiento, pero no demuestran que una skill sea correcta, segura o esté mantenida.
Tercero, los estándares para registros privados todavía están en formación. Puedes construir un registro muy útil con Git y CI, pero aún no existe un modelo empresarial universal para permisos, firmas, procedencia y aplicación de políticas en tiempo de ejecución.
Cuarto, el análisis de seguridad es necesario, pero incompleto. Un análisis estático sin hallazgos no garantiza un comportamiento seguro cuando la skill entra en una sesión activa de un agente.
Quinto, los equipos necesitan disciplina para gestionar el ciclo de vida. La parte difícil no es crear diez skills. La parte difícil es mantener cincuenta skills actualizadas después de que cambien la organización, las APIs, las herramientas y las políticas.
Secciones recomendadas para un artículo futuro
Este artículo presenta la arquitectura. Un artículo posterior podría profundizar en:
- un esquema completo de
registry.yaml - cómo firmar y verificar versiones de skills
- cómo medir si una skill realmente mejora los resultados de un agente
- una comparación entre registros de skills, servidores MCP y plugins tradicionales
- el diseño de un modelo de permisos para skills con scripts y acceso a la red
- la conversión de documentación existente del equipo en archivos
SKILL.mdde alta calidad - la construcción de una suite de evaluación que compruebe si las skills se activan en el momento adecuado
Reflexión final
Trata las skills como artefactos estrechamente relacionados con el código.
Son legibles como documentos, reutilizables como paquetes y operativas como la automatización. Eso las convierte en un híbrido peculiar, pero también muy útil.
Los directorios públicos como skills.sh muestran el patrón de descubrimiento. Un registro empresarial debe añadir la capa que falta para la empresa: confianza, responsables, revisión, implementación y mantenimiento.
Si solo haces una cosa este mes, haz esto:
Create a private company-agent-skills repo.
Add three useful skills.
Add owners and review.
Install them in one pilot team.
Measure what breaks.Eso basta para convertir prompts dispersos en un sistema colaborativo de skills.
Fuentes
- Anthropic: Cómo preparar agentes para el mundo real con Agent Skills - explica el formato Agent Skills,
SKILL.md, los metadatos y la divulgación progresiva. - Documentación de GitHub: Cómo añadir skills de agentes para GitHub Copilot - documenta el frontmatter de
SKILL.md, las ubicaciones de skills de proyecto y personales, y los scripts y recursos opcionales. - Catálogo de skills de OpenAI para Codex - muestra patrones de instalación de skills de Codex mediante
$skill-installer, skills seleccionadas, skills experimentales y URLs de directorios de GitHub. - Documentación de skills.sh - describe las skills como capacidades reutilizables para agentes de IA, el flujo de
npx skills add, la telemetría de clasificación, las insignias y las advertencias de seguridad. - Directorio de skills.sh - directorio público de skills de agentes indexadas y descubrimiento basado en cantidades de instalaciones.
- SkillsGate: El marketplace abierto de skills para agentes de IA - describe el descubrimiento público como impulsado por
skills.sh, un índice abierto de skills de GitHub. - Registro de cambios de Vercel: Presentación de skills, el ecosistema abierto de skills para agentes - describe el ecosistema
npx skillspara distintos agentes y los agentes de destino compatibles. - ¿Qué impide que las skills de agentes sean reutilizables? Evidencia de 138K archivos SKILL.md - analiza defectos de reutilización en archivos públicos de
SKILL.mdrelacionados con enrutamiento, portabilidad, organización de recursos y seguridad. - Dentro de SKILL.md: Ataques semánticos a la cadena de suministro en un registro de skills para agentes de IA - estudia las superficies de ataque del registro en el descubrimiento, la selección y la instalación.
- SkillGuard: Un framework de permisos para skills de agentes - propone una gobernanza centrada en permisos para las skills de agentes y su comportamiento en tiempo de ejecución.
- SkillReg: Registro privado de skills para agentes de IA - un ejemplo de la categoría emergente de productos de registro privado para compartir y gobernar skills empresariales.
- LoadoutHQ: Registro privado de skills para agentes de IA empresariales - otro ejemplo de un registro privado de skills enfocado en carpetas gobernadas y distribución empresarial.
- Documentación de GitHub: Endpoints de la API REST para GitHub Apps - documenta las instalaciones de GitHub App, la selección de repositorios, los permisos y las URLs de tokens de acceso de instalación.
- Documentación de GitHub: Endpoints de la API REST para contenido de repositorios - documenta las operaciones de creación y actualización de archivos y los permisos de contenido necesarios para los tokens de instalación de GitHub App.
- Documentación de GitHub: Endpoints de la API REST para pull requests - documenta la creación de pull requests y los permisos necesarios para los tokens de instalación de GitHub App.