Crie uma skill do Claude para o Shager: SKILL.md, estrutura de pastas e as regras que tornam a publicação em várias contas repetível

Uma skill do Claude para o Shager é uma pasta com um arquivo SKILL.md cujo frontmatter YAML tem um name e uma description, seguidos de instruções que dizem ao Claude como fazer a distribuição pelas ferramentas do Shager: quais chamadas fazer, em que ordem e quais regras nunca se dobram. Coloque-a em ~/.claude/skills/shager-distribution/ para uso pessoal ou em .claude/skills/shager-distribution/ dentro de um repositório para a equipe, e o Claude Code a carrega quando um pedido corresponde a ela, ou quando você digita /shager-distribution.

Conectar ao Shager é a parte fácil. A skill é onde você registra o critério: variação de legendas, links rastreáveis, rascunho como padrão e o que fazer quando a API diz não.

Por que escrever uma skill em vez de um prompt longo?

Porque o prompt que você aperfeiçoa na terça já se perdeu na quinta, e o colega que não o viu escreve um pior. A visão geral das Agent Skills da Anthropic descreve as skills como recursos do sistema de arquivos carregados sob demanda. Só o nome e a descrição ficam no contexto até a skill ser acionada. Aí o SKILL.md é lido, e os arquivos extras para os quais ele aponta só são lidos quando necessário. Então você pode ter instruções detalhadas sem pagar por elas em toda conversa.

No caso do Shager, o procedimento é estável enquanto o conteúdo muda toda semana. Esse é o perfil de uma boa skill.

Role para o lado para ver o diagrama inteiro

Quais são as regras do frontmatter do SKILL.md?

Segundo a mesma página de visão geral, name e description são obrigatórios. O name tem no máximo 64 caracteres, só letras minúsculas, números e hífens, e não pode conter as palavras reservadas "anthropic" nem "claude". A description não pode ser vazia, tem no máximo 1.024 caracteres e precisa dizer tanto o que a skill faz quanto quando usá-la, porque é com ela que o Claude compara os pedidos.

O Claude Code acrescenta campos opcionais, documentados em Use Skills in Claude Code: allowed-tools, para as ferramentas que o Claude pode usar sem pedir permissão enquanto a skill está ativa, disable-model-invocation, para que ela só funcione manualmente, argument-hint, para o autocompletar, entre outros. O nome da pasta, ou o name, quando definido, vira o comando de barra.

Como deve ser a estrutura de pastas?

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

O SKILL.md guarda o procedimento. O reference/tools.md guarda os detalhes campo a campo de create_post e upload_media_from_url, lidos só quando o Claude precisa. O scripts/shager.py é um plano B opcional via REST para ambientes sem o servidor MCP. A documentação do Claude Code recomenda manter o SKILL.md com menos de 500 linhas e levar os detalhes para arquivos separados, que é exatamente essa divisão.

O Shager também publica um arquivo de skill mantido pela equipe em https://shager.ai/skills/shager/SKILL.md. É um bom ponto de partida para ler antes de escrever a sua; a versão abaixo acrescenta regras específicas de agência.

O 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

Algumas decisões ali merecem ser defendidas.

A lista allowed-tools só tem operações de leitura. create_post, schedule_post, request_approval e cancel_post continuam pedindo permissão no Claude Code, então uma pessoa vê cada escrita. As ferramentas MCP se chamam mcp__<server>__<tool>, o que pressupõe que você registrou o servidor como shager, como em como conectar o Shager ao Claude Code.

A linha sobre o Instagram reflete como a rede funciona: links em legendas e comentários não são clicáveis lá. O primeiro comentário com o link rastreável faz diferença nas páginas do Facebook e no YouTube.

O "rascunho como padrão" é garantido duas vezes. Uma nas instruções, e outra dando ao ambiente da skill uma chave sem o escopo publish. As instruções orientam; os escopos garantem.

Role para o lado para ver o diagrama inteiro

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: o plano B via REST

Quando o MCP não está configurado, a skill ainda pode trabalhar pela API REST, descrita no documento OpenAPI. Uma função auxiliar pequena evita que o Claude improvise código HTTP a 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()

Acrescente ao SKILL.md uma linha como "If the shager MCP tools are unavailable, run scripts/shager.py with the same operation paths" e liste os caminhos em reference/tools.md. A página de visão geral observa que, quando o Claude roda um script incluído na skill, só a saída entra no contexto, não o código.

Onde a skill deve ficar?

Ambiente	Local	Consegue acessar o Shager?
Claude Code, pessoal	~/.claude/skills/shager-distribution/	Sim, via MCP ou pelo script. Skills ali têm o mesmo acesso à rede que qualquer programa na sua máquina
Claude Code, equipe	.claude/skills/shager-distribution/ versionada em um repositório	Sim, igual ao caso acima
claude.ai	Enviada como zip em Settings, Features	O acesso à rede varia conforme as configurações do usuário e do administrador
API do Claude	Enviada pela Skills API	Não: skills na API rodam sem acesso à rede

Essa última linha vem direto das restrições de execução descritas na visão geral, e pega muita gente de surpresa. Na API, use o servidor MCP do Shager ou as suas próprias chamadas de ferramentas para a parte de rede, e deixe a skill só com as instruções. Repare também que skills personalizadas não são sincronizadas entre ambientes; uma skill enviada ao claude.ai não aparece no Claude Code.

Como testar?

1. Peça algo que deveria acioná-la sem citar o nome: "Draft this week's open-day post for all Harbor Fitness locations." Confira se o Claude lê a skill.
2. Peça algo que não deveria: "What's a good caption length for Reels?" A skill deve ficar de fora.
3. Rode /shager-distribution Harbor Fitness https://example.com/clip.mp4 e confira se ela para na tabela de rascunhos.
4. Use uma chave sem publish e peça para agendar. Ela deve explicar o 403 em vez de entrar em loop.

Perguntas frequentes

O nome da skill pode incluir "claude"?

Não. As regras de skills da Anthropic reservam as palavras "anthropic" e "claude" no campo name. Use algo como shager-distribution; o título da sua documentação pode continuar dizendo que é uma skill do Claude.

A skill deve guardar a chave de API?

Não. Mantenha a chave na configuração do cliente MCP ou em uma variável de ambiente como SHAGER_API_KEY. Uma skill é uma pasta feita para ser compartilhada e muitas vezes vai parar no git; uma chave dentro dela acaba vazando.

A mesma skill funciona no Cursor ou no Codex?

O formato SKILL.md é da Anthropic, mas as instruções dentro dele são texto simples. Muitas equipes colam o conteúdo nas regras do Cursor ou em um arquivo de prompt do Codex. Os nomes das ferramentas são os mesmos em qualquer cliente, porque vêm do servidor MCP do Shager.

Próximo passo

Uma skill que cria rascunhos sob demanda é a base. O próximo artigo a transforma em uma rotina semanal de distribuição que planeja a semana, escreve os posts de cada cliente, encaminha as aprovações e reporta os cliques, com os pontos de controle humanos nos lugares certos.