Creare una skill di Claude per Shager: SKILL.md, struttura delle cartelle e le regole che rendono ripetibile la pubblicazione su più account

Una skill di Claude per Shager è una cartella con un file SKILL.md, il cui frontmatter YAML contiene un name e una description, seguito da istruzioni che spiegano a Claude come gestire la distribuzione tramite gli strumenti di Shager: quali chiamate fare, in che ordine e quali regole non si piegano mai. Mettila in ~/.claude/skills/shager-distribution/ per uso personale o in .claude/skills/shager-distribution/ in un repository per il tuo team, e Claude Code la carica quando una richiesta corrisponde, oppure quando digiti /shager-distribution.

Il collegamento a Shager è la parte facile. La skill è il posto in cui codifichi il giudizio: variazione dei testi, link tracciati, bozze come impostazione predefinita e cosa fare quando l'API dice di no.

Perché scrivere una skill invece di un prompt lungo?

Perché il prompt che perfezioni il martedì è sparito entro giovedì, e il collega che non l'ha visto ne scrive uno peggiore. La panoramica sulle Agent Skills di Anthropic descrive le skill come risorse del filesystem che si caricano su richiesta. Finché la skill non si attiva, nel contesto restano solo nome e descrizione. Poi viene letto SKILL.md, e gli eventuali file aggiuntivi a cui rimanda vengono letti solo quando servono. Così puoi permetterti istruzioni dettagliate senza pagarle in ogni conversazione.

Nel caso di Shager, la procedura resta stabile mentre i contenuti cambiano ogni settimana. È il profilo tipico di una buona skill.

Scorri di lato per vedere tutto il diagramma

Quali sono le regole per il frontmatter di SKILL.md?

Secondo la stessa pagina di panoramica, name e description sono obbligatori. name ha al massimo 64 caratteri, solo lettere minuscole, numeri e trattini, e non può contenere le parole riservate "anthropic" o "claude". description non può essere vuota, ha al massimo 1.024 caratteri e deve dire sia cosa fa la skill sia quando usarla, perché è su questo che Claude confronta le richieste.

Claude Code aggiunge campi facoltativi, documentati in Use Skills in Claude Code: allowed-tools per gli strumenti che Claude può usare senza chiedere mentre la skill è attiva, disable-model-invocation per renderla solo manuale, argument-hint per il completamento automatico e altri ancora. Il nome della cartella, oppure name se è impostato, diventa lo slash command.

Come deve essere fatta la cartella?

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

SKILL.md contiene la procedura. reference/tools.md contiene il dettaglio dei campi di create_post e upload_media_from_url, letto solo quando a Claude serve. scripts/shager.py è un ripiego REST facoltativo per gli ambienti senza il server MCP. La documentazione di Claude Code consiglia di tenere SKILL.md sotto le 500 righe e di spostare i dettagli in file separati, ed è esattamente questa divisione.

Shager pubblica anche un file di skill aggiornato su https://shager.ai/skills/shager/SKILL.md. È un buon punto di partenza da leggere prima di scrivere la tua; la versione qui sotto aggiunge regole specifiche per le agenzie.

Il file 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

Alcune scelte meritano di essere difese.

L'elenco allowed-tools contiene solo operazioni di lettura. create_post, schedule_post, request_approval e cancel_post continuano a chiedere il permesso in Claude Code, quindi una persona vede ogni scrittura. Gli strumenti MCP si chiamano mcp__<server>__<tool>, il che presuppone che tu abbia registrato il server come shager, come in collegare Shager a Claude Code.

La riga su Instagram rispecchia il comportamento del social: lì i link nei testi e nei commenti non sono cliccabili. Il primo commento con il link tracciato rende davvero sulle pagine Facebook e su YouTube.

"Bozze come impostazione predefinita" viene imposto due volte. Una nelle istruzioni, l'altra dando all'ambiente della skill una chiave senza il permesso publish. Le istruzioni guidano; i permessi impongono.

Scorri di lato per vedere tutto il diagramma

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: il ripiego REST

Quando MCP non è configurato, la skill può comunque funzionare tramite l'API REST, descritta nel documento OpenAPI. Un piccolo script di supporto evita che Claude improvvisi ogni volta il codice HTTP:

#!/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()

Aggiungi a SKILL.md una riga come "If the shager MCP tools are unavailable, run scripts/shager.py with the same operation paths" ed elenca i percorsi in reference/tools.md. La pagina di panoramica fa notare che, quando Claude esegue uno script incluso nella skill, nel contesto entra solo il suo output, non il codice.

Dove deve stare la skill?

Ambiente	Posizione	Può raggiungere Shager?
Claude Code, personale	~/.claude/skills/shager-distribution/	Sì, tramite MCP o lo script. Lì le skill hanno lo stesso accesso alla rete di qualsiasi programma sul tuo computer
Claude Code, team	.claude/skills/shager-distribution/ salvata in un repository	Sì, come sopra
claude.ai	Caricata come zip in Settings, Features	L'accesso alla rete dipende dalle impostazioni dell'utente e dell'amministratore
Claude API	Caricata tramite la Skills API	No: sull'API le skill girano senza accesso alla rete

L'ultima riga viene direttamente dai vincoli di esecuzione descritti nella panoramica, e sorprende molti. Sull'API, usa il server MCP di Shager o le tue chiamate agli strumenti per la parte di rete, e limita la skill alle istruzioni. Tieni anche presente che le skill personalizzate non si sincronizzano tra ambienti: una skill caricata su claude.ai non c'è in Claude Code.

Come si testa?

1. Chiedi qualcosa che dovrebbe attivarla senza nominarla: "Prepara la bozza del post per l'open day di questa settimana per tutte le sedi Harbor Fitness". Verifica che Claude legga la skill.
2. Chiedi qualcosa che non dovrebbe attivarla: "Qual è una buona lunghezza per il testo di un Reel?". La skill dovrebbe restarne fuori.
3. Esegui /shager-distribution Harbor Fitness https://example.com/clip.mp4 e verifica che si fermi alla tabella delle bozze.
4. Usa una chiave senza publish e chiedile di programmare. Dovrebbe spiegare il 403 invece di finire in un loop.

Domande frequenti

Il nome della skill può contenere "claude"?

No. Le regole di Anthropic per le skill riservano le parole "anthropic" e "claude" nel campo name. Usa qualcosa come shager-distribution; il titolo della tua documentazione può comunque dire che è una skill di Claude.

La skill deve contenere la chiave API?

No. Tieni la chiave nella configurazione del client MCP o in una variabile d'ambiente come SHAGER_API_KEY. Una skill è una cartella che si condivide e che spesso finisce in git; una chiave al suo interno finisce per trapelare.

La stessa skill funziona in Cursor o in Codex?

Il formato SKILL.md è di Anthropic, ma le istruzioni al suo interno sono testo semplice. Spesso i team incollano il corpo nelle regole di Cursor o in un file di prompt di Codex. I nomi degli strumenti sono gli stessi in ogni client, perché arrivano dal server MCP di Shager.

Prossimo passo

Una skill che prepara bozze su richiesta è la base. Il prossimo articolo la trasforma in una routine di distribuzione settimanale che pianifica la settimana, prepara le bozze dei post di ogni cliente, instrada le approvazioni e riporta i clic, con i controlli umani nei punti giusti.