---
name: siae-writing-skills
description: >
  Use when creating or improving DevForge skills (SKILL.md, behaviour change,
  template skill).
  Trigger: nuova skill DevForge, migliora skill, scrivi skill, behaviour change,
  template skill, progetta skill.
---

# Scrivere Skill DevForge Efficaci — Guida per Autori

```
╔══════════════════════════════════════════════════════════════════╗
║    ███████╗██╗ █████╗ ███████╗    ██████╗ ███████╗██╗   ██╗    ║
║    ██╔════╝██║██╔══██╗██╔════╝    ██╔══██╗██╔════╝██║   ██║    ║
║    ███████╗██║███████║█████╗      ██║  ██║█████╗  ██║   ██║    ║
║    ╚════██║██║██╔══██║██╔══╝      ██║  ██║██╔══╝  ╚██╗ ██╔╝    ║
║    ███████║██║██║  ██║███████╗    ██████╔╝███████╗ ╚████╔╝     ║
║    ╚══════╝╚═╝╚═╝  ╚═╝╚══════╝    ╚═════╝ ╚══════╝  ╚═══╝      ║
║              🔨 DevForge · WRITING SKILLS                     ║
║         "Il codice si forgia. Il developer cresce."            ║
╚══════════════════════════════════════════════════════════════════╝
```

> **Tipo:** Flexible | **Fase SDLC:** Meta (creazione skill)

---

> 📊 **Dai repo itsiae:** Skill scritte senza seguire il template siae-create-skill.md mancano in media 3.2 sezioni obbligatorie su 8.
> Fonte: analisi su 816 repository GitHub itsiae (60 Java, 44 HCL, 23 Python, 22 TypeScript).

## Obiettivo

Questa skill insegna a scrivere skill DevForge che **funzionano** — non solo documentazione,
ma strumenti di behaviour change che modificano realmente il modo in cui Claude opera.

Una skill ben scritta non si limita a descrivere un processo: lo **impone** attraverso
principi di persuasione, protocolli anti-razionalizzazione e verifica strutturata.

---

## I 3 Pilastri di una Skill Efficace

### 1. CSO — Claude Search Optimization

La `description` nel frontmatter e' il campo piu' importante della skill.
Claude la usa per decidere se caricarla. Se la description e' sbagliata, la skill non viene mai invocata.

**Regole:**
- La description descrive **trigger conditions ONLY**, mai il workflow
- Usa verbi all'imperativo: "Use when...", "Trigger: ..."
- Includi keyword che Claude associa al task: "bug fix", "feature", "commit"
- NON riassumere cosa fa la skill — descrivi QUANDO si applica
- Massimo 3 righe — Claude scansiona velocemente

**Esempio buono:**
```yaml
description: >
  Use when about to claim work is complete, fixed, or passing — requires
  running verification commands before any success claims. Trigger: prima
  di commit, PR, task complete, dichiarazioni di successo.
```

**Esempio cattivo:**
```yaml
description: >
  Questa skill implementa un protocollo di verifica a 5 step che garantisce
  la qualita' del codice attraverso esecuzione di test e analisi dell'output.
```

### 2. Struttura che Forza il Comportamento

Una skill non e' un documento da leggere. E' un **protocollo da eseguire**.

| Elemento | Funzione | Obbligatorio? |
|----------|----------|---------------|
| Frontmatter YAML | Trigger e metadata | Si |
| Banner DevForge | Identita' visiva, autorevolezza | Si |
| Legge di Ferro | Principio non negoziabile (1 frase) | Si (Rigid) |
| Step numerati | Workflow eseguibile | Si (Task) |
| Tabella Anti-Razionalizzazione | Blocca scorciatoie cognitive | Si (Rigid) |
| Classificazione Rischio | Pre-flight card awareness | Si |
| Vincoli | Guardrail espliciti | Si |
| Reference files | Dettagli per chi vuole approfondire | Consigliato |

### 3. Principi di Persuasione

Le skill DevForge usano principi di scienza della persuasione per massimizzare
la compliance di Claude. Vedi [reference/persuasion-principles.md](reference/persuasion-principles.md)
per l'approfondimento completo.

**Quick Reference — Principi per tipo di skill:**

| Tipo Skill | Top 3 Principi | Esempio |
|------------|----------------|---------|
| **Rigid** (TDD, verification, debugging) | Authority, Commitment, Scarcity | Legge di Ferro, Iron Law, "non negoziabile" |
| **Flexible** (architecture, standards) | Social Proof, Authority, Consistency | Pattern osservati in 60+ repo, standard SIAE |
| **Meta** (using-devforge, writing-skills) | Authority, Unity, Reciprocity | "DevForge Visual Design System", "La skill ti guida" |

---

## Workflow per Creare una Skill

### Step 1 — Definisci il Problema

Prima di scrivere, rispondi a queste domande:

1. **Quale comportamento vuoi cambiare?** (non "cosa vuoi documentare")
2. **Quale razionalizzazione impedisce il comportamento corretto?**
3. **Qual e' il costo della non-compliance?** (bug, sicurezza, debito tecnico)
4. **Rigid o Flexible?** Le skill di processo sono Rigid. Le skill di dominio sono Flexible.

### Step 2 — Scrivi i Test

Applica TDD alla documentazione. Vedi [reference/testing-skills.md](reference/testing-skills.md).

1. Scrivi un prompt di test che dovrebbe attivare la skill
2. Scrivi un "pressure scenario" che tenta di bypassare la skill
3. Definisci i criteri di successo (cosa deve fare Claude con la skill attiva)

### Step 3 — Scrivi il SKILL.md

| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-writing-skills |
|:---|
| 🛠️ Operazione: `Creazione directory skill` · 📁 Skill: `<nome skill che si sta creando>` |
| **▼ Azione** |
| 1. ✏️ Crea directory → `skills/<nome-skill>/` |
| 💡 Perche': Un nome errato o duplicato rompe il catalogo skill e la discovery automatica. |
| 🚫 Se NO: La directory skill non viene creata e nessun file viene scritto. |

| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-writing-skills |
|:---|
| 🛠️ Operazione: `Scrittura SKILL.md e reference files` · 📁 Skill: `<nome skill che si sta creando>` |
| **▼ Azione** |
| 1. ✏️ Scrivi SKILL.md → `skills/<nome-skill>/SKILL.md` |
| 2. ✏️ Scrivi reference files → `skills/<nome-skill>/reference/` |
| 💡 Perche': Errori nel frontmatter o nella struttura impediscono la corretta attivazione da parte di Claude. |
| 🚫 Se NO: SKILL.md e i file reference non vengono scritti; la skill non esiste nel plugin. |

Usa il template in [reference/skill-template.md](reference/skill-template.md).

**Budget token:** massimo **500 righe** per SKILL.md. Sposta i dettagli nei file `reference/`.

**Struttura obbligatoria:**
1. Frontmatter YAML (name, description)
2. Banner DevForge
3. Tipo e Fase SDLC
4. Legge di Ferro (per skill Rigid)
5. "Quando si Applica"
6. Step numerati con etichette rischio
7. Tabella Anti-Razionalizzazione (per skill Rigid)
8. Classificazione Rischio Operazioni
9. Vincoli
10. Risorse Aggiuntive (link a reference/)

### Step 4 — Cross-referencing

| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-writing-skills |
|:---|
| 🛠️ Operazione: `Modifica using-devforge per registrazione` · 📁 Skill: `<nome skill che si sta creando>` |
| **▼ Azione** |
| 1. ✏️ Registra skill in using-devforge → `skills/using-devforge/SKILL.md` |
| 💡 Perche': Un errore nella registrazione rende la skill invisibile o rompe la discovery per tutti i developer. |
| 🚫 Se NO: La skill non viene registrata in using-devforge e non sara' inclusa nel catalogo attivo del plugin. |

Per referenziare altre skill, usa il pattern `REQUIRED SUB-SKILL:`:

```
REQUIRED SUB-SKILL: siae-verification
```

Questo dice a Claude di invocare la skill specificata come prerequisito.
**NON usare** `@file-path` o path assoluti — usa sempre il nome della skill.

### Step 5 — Valida

| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-writing-skills |
|:---|
| 🛠️ Operazione: `Test di attivazione con prompt` · 📁 Skill: `<nome skill che si sta creando>` |
| **▼ Azione** |
| 1. ✏️ Esegui prompt di attivazione → `skills/<nome-skill>/SKILL.md` |
| 💡 Perche': Un test su una skill mal configurata puo' dare falsi positivi e mascherare problemi di trigger. |
| 🚫 Se NO: Il test di attivazione non viene eseguito e non si ha garanzia che la skill funzioni in produzione. |

Checklist di validazione:

- [ ] `name` e' lowercase con trattini, max 64 char
- [ ] `description` descrive trigger conditions, non workflow
- [ ] SKILL.md e' sotto 500 righe
- [ ] Banner DevForge presente
- [ ] Ogni step ha etichetta rischio
- [ ] Tabella anti-razionalizzazione presente (se Rigid)
- [ ] Classificazione rischio operazioni presente
- [ ] Vincoli definiti
- [ ] Reference files linkati da SKILL.md
- [ ] Test di attivazione superato (prompt naturale → skill si attiva)

---

## Limiti Operativi

| Vincolo | Limite | Se superato |
|---------|--------|-------------|
| Tentativi fix per errore | 2 | Fermati. Diagnosi diversa necessaria. |
| File modificati per singolo step | 5 | Se devi toccare piu' file, decomponi in sub-task. |
| Output max per raccomandazione | 200 righe | Prioritizza. Top 5 issue, non lista esaustiva. |

---

```
REQUIRED SUB-SKILL: siae-verification
```
Invoca `siae-verification` per validare la skill contro il template siae-create-skill.md.

## Errori Comuni

| Errore | Perche' e' un Problema | Fix |
|--------|----------------------|-----|
| Description troppo lunga | Claude non la legge tutta | Max 3 righe, solo trigger |
| Description descrive il workflow | Claude non trova i trigger | Riscrivi con "Use when..." |
| Nessuna Legge di Ferro | La skill non ha un punto focale | Aggiungi una frase non negoziabile |
| Step senza etichette rischio | Le pre-flight card non si attivano | Classifica ogni step |
| Nessuna tabella anti-razionalizzazione | Claude puo' bypassare la skill | Aggiungi 8-12 razionalizzazioni |
| SKILL.md troppo lungo (> 500 righe) | Consumo contesto eccessivo | Sposta dettagli in reference/ |
| Path assoluti ai file | Si rompono se il plugin si sposta | Usa nomi skill e link relativi |
| Nessun test | Non sai se la skill funziona | Scrivi prompt di test e pressure scenario |

---

## Classificazione Rischio Operazioni

| Operazione | Livello | Card |
|-----------|---------|------|
| Analisi requisiti skill | 🟢 Sicuro | No |
| Lettura skill esistenti come riferimento | 🟢 Sicuro | No |
| Creazione directory skill | 🟡 Medio | Si |
| Scrittura SKILL.md e reference files | 🟡 Medio | Si |
| Modifica using-devforge per registrazione | 🟡 Medio | Si |
| Test di attivazione con prompt | 🟡 Medio | Si |

---

## Vincoli

1. **OGNI** skill generata deve seguire il Visual Design System DevForge
2. **MAI** superare 500 righe per SKILL.md
3. **MAI** usare path assoluti — solo nomi skill e link relativi
4. **SEMPRE** includere almeno una tabella anti-razionalizzazione per skill Rigid
5. **SEMPRE** classificare le operazioni per livello di rischio
6. **PRE-FLIGHT OBBLIGATORIA** per scrittura file (rischio >= 🟡)

---

## Risorse Aggiuntive

- [reference/persuasion-principles.md](reference/persuasion-principles.md) — 7 principi Cialdini adattati a DevForge
- [reference/testing-skills.md](reference/testing-skills.md) — TDD per documentazione (RED-GREEN-REFACTOR su skill)
- [reference/skill-template.md](reference/skill-template.md) — Template SKILL.md pronto all'uso