Crea una skill de Claude para Shager: SKILL.md, estructura de carpetas y las reglas que vuelven repetible la publicación en muchas cuentas

Una skill de Claude para Shager es una carpeta con un archivo SKILL.md cuyo frontmatter YAML tiene un name y una description, seguidos de instrucciones que le dicen a Claude cómo gestionar la distribución con las herramientas de Shager: qué llamadas hacer, en qué orden y qué reglas no se negocian nunca. Ponla en ~/.claude/skills/shager-distribution/ para tu uso personal o en .claude/skills/shager-distribution/ dentro de un repositorio para tu equipo, y Claude Code la cargará cuando una solicitud coincida o cuando escribas /shager-distribution.

La conexión con Shager es lo fácil. La skill es donde codificas el criterio: variación de los textos, enlaces con seguimiento, borradores por defecto y qué hacer cuando la API dice que no.

¿Por qué escribir una skill en lugar de un prompt largo?

Porque el prompt que perfeccionas el martes desaparece el jueves, y el compañero que no lo vio escribe uno peor. La introducción a las Agent Skills de Anthropic describe las skills como recursos del sistema de archivos que se cargan bajo demanda. Hasta que la skill se activa, en el contexto solo están el nombre y la descripción. Luego se lee SKILL.md, y los archivos adicionales a los que apunta se leen solo cuando hacen falta. Así puedes permitirte instrucciones detalladas sin pagarlas en cada conversación.

En el caso de Shager, el procedimiento es estable mientras el contenido cambia cada semana. Ese es el perfil de una buena skill.

Desliza hacia los lados para ver todo el diagrama

¿Cuáles son las reglas del frontmatter de SKILL.md?

Según esa misma página, name y description son obligatorios. name tiene como máximo 64 caracteres, solo letras minúsculas, números y guiones, y no puede contener las palabras reservadas "anthropic" ni "claude". description no puede estar vacía, tiene como máximo 1.024 caracteres y debe decir tanto qué hace la skill como cuándo usarla, porque es contra eso que Claude compara las solicitudes.

Claude Code agrega campos opcionales, documentados en Use Skills in Claude Code: allowed-tools para las herramientas que Claude puede usar sin pedir permiso mientras la skill está activa, disable-model-invocation para que solo se use de forma manual, argument-hint para el autocompletado, entre otros. El nombre de la carpeta, o name si está definido, se convierte en el comando de barra.

¿Cómo debería ser la carpeta?

shager-distribution/
  SKILL.md
  reference/
    tools.md
    errors.md
  scripts/
    shager.py

SKILL.md contiene el procedimiento. reference/tools.md contiene el detalle a nivel de campo de create_post y upload_media_from_url, y solo se lee cuando Claude lo necesita. scripts/shager.py es una alternativa REST opcional para entornos sin el servidor MCP. La documentación de Claude Code recomienda mantener SKILL.md por debajo de 500 líneas y pasar el detalle a archivos separados, que es exactamente esta división.

Shager también publica un archivo de skill mantenido en https://shager.ai/skills/shager/SKILL.md. Es un buen punto de partida para leer antes de escribir el tuyo; la versión de abajo suma reglas propias de una agencia.

El SKILL.md

---
name: shager-distribution
description: Distribute a post or video to many social accounts through Shager (Facebook Pages, Instagram professional accounts, YouTube channels). Use when the user asks to post, schedule, draft or distribute content to client accounts, account groups or "all locations", or asks which account drove clicks.
argument-hint: "[workspace] [brief or media URL]"
allowed-tools: mcp__shager__whoami mcp__shager__list_workspaces mcp__shager__list_channels mcp__shager__list_groups mcp__shager__get_post mcp__shager__list_posts mcp__shager__get_analytics
---

# Shager distribution

## Before anything
1. Call whoami. Note the scopes and whether this is a sandbox.
2. Resolve the workspace by name with list_workspaces. If two match, ask.
3. Call list_channels and list_groups. Only target channels with status ACTIVE.

## Building the post
1. Media: call upload_media_from_url. For vertical video pass width,
   height and duration_ms so Shager can validate Reels, Shorts and Stories.
2. Captions: write one caption per channel in per_channel. Keep facts,
   prices and dates identical; vary the opening line, structure and the
   local detail (city, branch, presenter) taken from the channel name.
3. Links: never paste a raw URL into captions. Pass it as cta_url so each
   account gets its own short link and UTM tags. Put the call to action
   in first_comment for Facebook and YouTube. Instagram does not make
   comment links clickable, so for Instagram channels mention "link in bio".
4. Set campaign to a lowercase slug, e.g. "spring-open-day-2026".
5. Set label to something a human will recognize in the calendar.

## Drafts by default
Create the post WITHOUT schedule_at unless the user gave an explicit date
and time in this conversation. Show a table of channel, network, format and
the first line of each caption, and wait for confirmation.

## Scheduling
Only when confirmed: call schedule_post with schedule_at in ISO 8601 with
the workspace's UTC offset. If the workspace requires approval, call
request_approval instead and return the approval_url to the user.

## When Shager says no
Read error.code, do not retry blindly. See reference/errors.md.

## Reporting
For "how did it do", call get_analytics for the date range and present
clicks by account, highest first, plus the top posts.

Field details for create_post: reference/tools.md

Hay algunas decisiones ahí que vale la pena defender.

La lista allowed-tools solo contiene operaciones de lectura. create_post, schedule_post, request_approval y cancel_post siguen pidiendo permiso en Claude Code, así que una persona ve cada escritura. Las herramientas MCP se llaman mcp__<server>__<tool>, lo que da por hecho que registraste el servidor como shager, como en conectar Shager con Claude Code.

La línea sobre Instagram refleja cómo se comporta esa red: los enlaces en los textos y en los comentarios no son clicables. El primer comentario con el enlace con seguimiento rinde en las páginas de Facebook y en YouTube.

"Borradores por defecto" se aplica dos veces. Una en las instrucciones, y otra al darle al entorno de la skill una clave sin el permiso publish. Las instrucciones orientan; los permisos imponen.

Desliza hacia los lados para ver todo el diagrama

reference/errors.md

# Shager error codes

401 unauthorized: key missing or malformed. Stop and tell the user.
403 forbidden: key lacks a scope. If scheduling, say a human must schedule
    or grant publish at app.shager.ai/dashboard/agents.
403 sandbox_unclaimed: show the claim link from signup; nothing else to do.
404 not_found: re-list channels or posts; ids are per workspace.
409 not_scheduled: the post is not scheduled; get_post and report status.
422 rejected: a network rule failed. Quote the message, fix the input
    (length, format, media), and try once more.
429 rate_limited: wait 60 seconds, then continue. Never loop per account.

scripts/shager.py: la alternativa REST

Cuando MCP no está configurado, la skill igual puede funcionar a través de la API REST, descrita en el documento OpenAPI. Una pequeña función auxiliar evita que Claude improvise código HTTP cada vez:

#!/usr/bin/env python3
"""Usage: shager.py METHOD PATH [JSON_BODY]
Example: shager.py GET /workspaces
         shager.py POST /workspaces/WS_ID/posts '{"caption": "..."}'"""
import json, os, sys, requests

API = "https://app.shager.ai/api/v1"

def main():
    method, path = sys.argv[1].upper(), sys.argv[2]
    body = json.loads(sys.argv[3]) if len(sys.argv) > 3 else None
    r = requests.request(
        method, f"{API}{path}",
        headers={"Authorization": f"Bearer {os.environ['SHAGER_API_KEY']}"},
        json=body, timeout=90,
    )
    payload = r.json()
    if not r.ok:
        e = payload["error"]
        print(json.dumps({"status": r.status_code, "code": e["code"], "message": e["message"]}))
        sys.exit(1)
    print(json.dumps(payload["data"], indent=2))

if __name__ == "__main__":
    main()

Agrega una línea a SKILL.md como "If the shager MCP tools are unavailable, run scripts/shager.py with the same operation paths" y enumera las rutas en reference/tools.md. La página de introducción señala que, cuando Claude ejecuta un script incluido en la skill, al contexto solo entra su salida, no el código.

¿Dónde debería vivir la skill?

Entorno	Ubicación	¿Puede llegar a Shager?
Claude Code, personal	~/.claude/skills/shager-distribution/	Sí, por MCP o con el script. Las skills ahí tienen el mismo acceso a la red que cualquier programa de tu máquina
Claude Code, equipo	.claude/skills/shager-distribution/ en un repositorio	Sí, igual que arriba
claude.ai	Subida como zip en Settings, Features	El acceso a la red depende de la configuración del usuario y del administrador
Claude API	Subida a través de la Skills API	No: las skills en la API se ejecutan sin acceso a la red

Esa última fila sale directamente de las restricciones de ejecución que describe la introducción, y sorprende a más de uno. En la API, usa el servidor MCP de Shager o tus propias llamadas a herramientas para la parte de red, y deja la skill solo para las instrucciones. Ten en cuenta también que las skills personalizadas no se sincronizan entre entornos: una skill subida a claude.ai no está en Claude Code.

¿Cómo se prueba?

1. Pide algo que debería activarla sin nombrarla: "Prepara el borrador de la publicación de puertas abiertas de esta semana para todas las sedes de Harbor Fitness". Comprueba que Claude lee la skill.
2. Pide algo que no debería activarla: "¿Qué largo de texto conviene para un Reel?". La skill debería quedarse al margen.
3. Ejecuta /shager-distribution Harbor Fitness https://example.com/clip.mp4 y comprueba que se detiene en la tabla de borradores.
4. Usa una clave sin publish y pídele que programe. Debería explicar el 403 en lugar de entrar en un bucle.

Preguntas frecuentes

¿El nombre de la skill puede incluir "claude"?

No. Las reglas de skills de Anthropic reservan las palabras "anthropic" y "claude" en el campo name. Usa algo como shager-distribution; el título de tu documentación sí puede decir que es una skill de Claude.

¿La skill debería guardar la clave de API?

No. Guarda la clave en la configuración del cliente MCP o en una variable de entorno como SHAGER_API_KEY. Una skill es una carpeta pensada para compartirse y muchas veces termina en git; una clave guardada ahí termina filtrada.

¿La misma skill funciona en Cursor o en Codex?

El formato SKILL.md es de Anthropic, pero las instrucciones que contiene son texto plano. Muchos equipos pegan el cuerpo en las reglas de Cursor o en un archivo de prompt de Codex. Los nombres de las herramientas son los mismos en todos los clientes, porque vienen del servidor MCP de Shager.

Siguiente paso

Una skill que redacta borradores cuando se lo pides es la base. El siguiente artículo la convierte en una rutina de distribución semanal que planifica la semana, redacta las publicaciones de cada cliente, gestiona las aprobaciones y reporta los clics, con los puntos de control humanos en los lugares correctos.