---
title: "Skills per Claude e Codex: costruire una review e vedere quando parte"
source: "https://www.matteovincenti.com/blog/ottimizzare-skills-claude-codex"
language: it
author: "Matteo Vincenti"
published: 2026-10-20
updated: 2026-10-23
category: "AI"
tags: ["Agent Skills", "Claude Code", "Codex"]
---

# Skills per Claude e Codex: costruire una review e vedere quando parte

Crea una skill di code review per Claude e Codex. Il laboratorio confronta due descrizioni in quattro sessioni Codex, con risultati osservati e limiti.

![Una dima verde produce forme ripetibili da un foglio chiaro](https://cdn.sanity.io/images/xrqkwry7/production/92a60a3e84ea4ccd2aa8070817ec50954bb3ab2f-1727x910.png?w=1400&fit=max&auto=format)

Categoria: AI · Tag: Agent Skills, Claude Code, Codex

Se chiedo a un agente di spiegarmi una funzione, mi interessa che la spiegazione sia corretta. Per quella richiesta eviterei di fargli caricare anche istruzioni, rubrica e formato di una code review. Per valutare una skill, quindi, guardo sia il risultato sia il percorso che l’agente ha seguito.

Il laboratorio di questa guida confronta due descrizioni della stessa skill, un pacchetto di istruzioni riutilizzabili per l’agente. La descrizione ampia includeva anche le spiegazioni di codice. Con quella descrizione, Codex ha aperto i tre file della review prima di spiegare discountedTotal; nella sessione con la descrizione circoscritta non sono state osservate quelle letture. Le due richieste di review hanno trovato entrambe il difetto introdotto. È una differenza che userei per scegliere che cosa tenere nel catalogo.

## Che cosa installiamo

Una skill è un pacchetto di istruzioni riutilizzabili per un’attività. Il file principale, `SKILL.md`, contiene un’intestazione YAML con nome e descrizione, seguita dalla procedura. Altri file possono fornire criteri, formati o script. La [specifica Agent Skills](https://agentskills.io/specification) definisce il formato comune; Claude Code e Codex aggiungono modalità proprie di scoperta e invocazione.

All’inizio il client rende disponibili i metadati delle skill. Quando ne viene scelta una, carica le istruzioni; i riferimenti si leggono quando servono. Per questo la descrizione deve indicare il lavoro giusto prima ancora di spiegare come eseguirlo. Il corpo della skill non può correggere una selezione sbagliata se non viene mai aperto.

Per questo esempio partirei dalla review di un diff: ha una modifica precisa da leggere e un contratto con cui confrontarla. Nel laboratorio il difetto è noto e i test permettono di controllare il rilievo; posso quindi osservare separatamente la selezione della skill e il risultato della review. Le regole permanenti del progetto restano in `AGENTS.md` o `CLAUDE.md`. Nella skill raccolgo i passaggi richiesti quando viene chiesta una review, distribuiti fra istruzioni, rubrica e formato del rapporto.

## Preparare il laboratorio

Servono Git, Node.js con il test runner integrato e almeno uno dei due client installato e autenticato. I comandi seguenti usano una shell compatibile con Bash. La prova riportata più avanti è stata eseguita con Codex CLI 0.163.0 e Node 24.19.0; il percorso Claude segue la documentazione, senza una prova runtime in questo laboratorio.

Crea una cartella nuova e aprila:

```bash
mkdir skills-lab
cd skills-lab
git init -q
```

La struttura per Codex sarà questa. Per Claude cambia soltanto il contenitore da `.agents/skills` a `.claude/skills`; i tre file della skill hanno lo stesso contenuto.

```txt
skills-lab/
├── README.md
├── discount.mjs
├── discount.test.mjs
└── .agents/skills/review-change/
    ├── SKILL.md
    ├── references/review-rubric.md
    └── assets/result-format.md
```

Nel file `README.md` scrivi il contratto da verificare:

```markdown
# Discount fixture
This is a synthetic review example.
The percentage accepts finite values from 0 through 100 inclusive. A full discount is valid and returns zero.
Run node --test discount.test.mjs. The requested change is the uncommitted diff in discount.mjs.
```

Salva questa implementazione in `discount.mjs`:

```javascript
export function discountedTotal(price, percent) {
  if (!Number.isFinite(price) || price < 0) throw new RangeError('price');
  if (!Number.isFinite(percent) || percent < 0 || percent > 100) throw new RangeError('percent');
  return price * (1 - percent / 100);
}
```

E questi quattro casi in `discount.test.mjs`:

```javascript
import test from 'node:test';
import assert from 'node:assert/strict';
import {discountedTotal} from './discount.mjs';
test('ordinary discount', () => assert.equal(discountedTotal(100, 20), 80));
test('no discount', () => assert.equal(discountedTotal(100, 0), 100));
test('full discount is valid', () => assert.equal(discountedTotal(100, 100), 0));
test('out of range is rejected', () => assert.throws(() => discountedTotal(100, 101), RangeError));
```

Esegui il controllo iniziale e registra la base del confronto nel repository dimostrativo. L’identità indicata serve soltanto per questo commit:

```bash
node --test discount.test.mjs
git add README.md discount.mjs discount.test.mjs
git -c user.name="Skills lab" -c user.email="skills-lab@example.invalid" commit -qm "Add discount contract and tests"
```

I quattro test devono passare. Ora, nella seconda condizione di `discount.mjs`, sostituisci `percent > 100` con `percent >= 100`, senza committare la modifica. Il diff deve mostrare soltanto questa regressione:

```diff
-  if (!Number.isFinite(percent) || percent < 0 || percent > 100) throw new RangeError('percent');
+  if (!Number.isFinite(percent) || percent < 0 || percent >= 100) throw new RangeError('percent');
```

Ripetendo il test, il caso `full discount is valid` fallisce: il contratto ammette il 100%, mentre la nuova condizione lo rifiuta. Questo risultato atteso permette di controllare la review dell’agente senza affidarsi alla sua autovalutazione.

## I tre file della skill

Per Codex crea le directory con:

```bash
mkdir -p .agents/skills/review-change/references .agents/skills/review-change/assets
```

In Claude usa gli stessi sottopercorsi dentro `.claude/skills/review-change`. Salva `SKILL.md` nella directory `review-change`:

```markdown
---
name: review-change
description: Review a specified diff for correctness and regressions. Use when asked to review a change before commit or merge. Do not use for explanation-only requests.
---

Review the requested change without editing it.

1. Establish the requested diff or revision range. If the target is
   materially ambiguous, ask for the missing scope.
2. Read applicable repository instructions and inspect the diff.
3. Follow affected call sites and tests only as needed to assess
   a concrete risk. Use references/review-rubric.md for the rubric.
4. Run relevant, authorized checks when useful and feasible.
   Record checks that could not run and the reason.
5. Report actionable findings with file locations, the failure
   condition, and its consequence. Do not invent findings.
6. Separate findings from open questions and verification limits.

Use assets/result-format.md to format the result.
Do not claim that unrun checks passed.
Do not commit, push, merge, or publish.
```

La descrizione completa nomina la review di una modifica prima di commit o merge ed esclude le richieste di sola spiegazione. È la scelta che propongo anche fuori da questo esempio: scrivere il compito che deve far scegliere la skill, senza aggiungere attività che la procedura non serve a svolgere. Il corpo può così concentrarsi sul diff, sulle parti coinvolte e sul collegamento tra difetto, condizione e conseguenza.

In `references/review-rubric.md` metti i criteri:

```markdown
# Review rubric

Prioritize failures in the changed behavior.

For boundary changes, check empty, missing, and invalid values.
For state changes, check retries, partial failure, and duplicate actions.
For public contracts, inspect affected callers and compatibility.
For performance claims, require an appropriate measurement.

A finding must explain a plausible trigger and consequence.
Do not report a theoretical concern without a code-supported path.
State uncertainty when evidence is incomplete.
```

In `assets/result-format.md` metti il formato:

```markdown
# Findings

For each finding: severity, location, trigger, consequence, evidence.
If there are no supported findings, say so.

# Verification

List checks actually run and their results.
List unrun checks and material limits.

# Open questions

Include only unresolved questions that affect the review.
```

Per questo esempio tre file sono sufficienti. Tengo il confine del compito e la procedura in `SKILL.md`, separo i criteri nella rubrica e lascio il formato del rapporto in un file dedicato. Se cambia il modo di presentare i difetti, so quale file modificare; se manca un criterio, posso aggiungerlo senza allungare la descrizione mostrata al client. I due file di supporto sono richiamati dalla procedura: la loro sola presenza nella cartella non basta a farli leggere.

## Richiamarla e vedere che cosa succede

Apri il client nella radice di `skills-lab`, dopo aver salvato i file. In Codex CLI o IDE puoi verificare la presenza nel selettore `/skills` e richiamare esplicitamente `$review-change`. In Claude Code il comando è `/review-change`. La scoperta locale è descritta nelle guide [Codex](https://learn.chatgpt.com/docs/build-skills) e [Claude Code](https://code.claude.com/docs/en/skills); se la skill appena creata non compare, riparti da una nuova sessione prima di cambiare le istruzioni.

Il richiamo esplicito risponde alla domanda «il client riesce a usare questo pacchetto?». Per vedere quando lo sceglie da solo, formula invece una normale richiesta, senza nominare la skill:

```txt
Spiegami cosa fa discountedTotal in discount.mjs e quali valori accetta. Rispondi in italiano.
```

Poi apri una sessione nuova e chiedi:

```txt
Fai la review della modifica non committata in discount.mjs rispetto al contratto nel README. Indica solo problemi concreti con file e righe; non modificare i file. Rispondi in italiano.
```

Per conservare gli eventi di una sessione Codex puoi usare il comando non interattivo. La directory dei risultati è esterna al progetto, così la traccia non entra fra i file che l’agente sta esaminando:

```bash
skills_run_dir=$(mktemp -d)
codex exec --ignore-user-config --ephemeral --sandbox read-only --json \
  --cd "$PWD" \
  "Spiegami cosa fa discountedTotal in discount.mjs e quali valori accetta. Rispondi in italiano." \
  > "$skills_run_dir/explanation.jsonl"
```

Usa lo stesso comando con il prompt di review e un altro nome di output. `--ephemeral` evita la conservazione della sessione e `--sandbox read-only` limita le scritture dei comandi dell’agente. `--ignore-user-config` esclude il file di configurazione utente, ma non dimostra che siano assenti tutte le skill personali o le impostazioni gestite. Annotale quando confronti i risultati.

Nel JSONL cerca gli eventi completati: quale comando ha letto `SKILL.md`, quali riferimenti ha aperto, se ha eseguito i test e con quale esito. La frase «ho usato la skill» non aggiunge una prova a ciò che la traccia mostra. Questa distinzione è anche alla base della guida OpenAI sugli [eval delle skill](https://developers.openai.com/blog/eval-skills).

## Due descrizioni, quattro osservazioni

La descrizione ampia usata nel confronto era:

```yaml
description: Improve code. Use this skill for code explanations, bugs, performance, tests and quality.
```

L’altra è quella del file completo: review di un diff, con esclusione delle richieste di sola spiegazione. Per ripetere il confronto, prepara due copie del laboratorio con la medesima modifica e gli stessi tre file, cambiando soltanto quella riga. Usa una sessione nuova per ciascuna delle due richieste in ciascuna copia.

Prima di ripetere la prova, fissa due esiti attesi: una spiegazione pertinente e una review che individui il difetto del 100%. Registra a parte letture e test.

Nelle quattro sessioni Codex osservate:

_Due descrizioni, quattro osservazioni_

| Descrizione e richiesta | Letture della skill nella traccia | Risultato |
| --- | --- | --- |
| Ampia, spiegazione | `SKILL.md`, rubrica e formato | Spiegazione della funzione; nessun test eseguito |
| Circoscritta, spiegazione | Nessuna lettura dei tre file osservata | Spiegazione della funzione; nota sulla discordanza con i test |
| Ampia, review | Tutti e tre i file | Difetto del 100% individuato; test eseguiti: tre passano e uno fallisce |
| Circoscritta, review | Tutti e tre i file | Stesso difetto individuato; test non eseguiti |

Il risultato che considero utile è la differenza nella selezione: nella sessione di spiegazione con la descrizione circoscritta non compaiono le letture dei tre file. Le due review hanno trovato lo stesso difetto; queste osservazioni non mostrano un miglioramento della qualità della review. I file del laboratorio e della skill sono rimasti invariati durante le sessioni.

Prima di adottare la descrizione circoscritta, guarderei anche come viene svolta la review: la review con la descrizione circoscritta ha trovato il problema leggendo il diff senza eseguire i test. La procedura li consente quando sono utili e fattibili. In un processo che li richiede sempre, renderei esplicito l’obbligo e farei controllare l’esito al workflow: il rilievo corretto da solo non soddisfa quel requisito.

Sono quattro osservazioni su una fixture, con il client e l’ambiente dichiarati. La traccia non espone il modello risolto né l’intero catalogo effettivo, quindi non uso questi run per stimare risparmio di token, affidabilità generale o differenze con Claude. Il difetto è inoltre abbastanza semplice da essere trovato anche senza skill: qui si vede il percorso seguito, non un confronto con una baseline priva di istruzioni.

## Quando la skill non parte, o parte troppo spesso

Se manca dal selettore, controlla percorso, nome e intestazione YAML. In Codex il percorso di progetto è `.agents/skills`; in Claude è `.claude/skills`. Una skill presente solo nella cartella personale del tuo computer non è automaticamente disponibile in un ambiente cloud. Verifica anche che un altro pacchetto non usi lo stesso nome.

Se è visibile e funziona quando la richiami, ma viene ignorata nelle richieste normali, lavora sulla descrizione e sulle frasi di prova. Un confine troppo stretto può escludere una review legittima formulata in altro modo. Se invece parte per spiegazioni e domande generiche, togli i compiti che non appartengono alla procedura. Conserva le richieste che hanno mostrato l’errore: diventano casi da ricontrollare alla modifica successiva.

Claude Code documenta anche `/skill-doctor` dalla versione 2.1.252 per esaminare costo di contesto e uso delle skill, e `claude plugin validate .claude/skills` dalla 2.1.233 per controllare staticamente il frontmatter YAML della directory. `/skill-doctor` richiede il recupero dei feature flag e non è disponibile tramite Remote Control; i dettagli sono nella [documentazione Claude Code](https://code.claude.com/docs/en/skills#find-unused-skills). Sono controlli diversi dalla prova di una review. In Codex, `/skills` permette di controllare il catalogo; il comando `codex exec --json` serve a osservare l’esecuzione.

I controlli di invocazione dipendono dal client. Claude supporta `disable-model-invocation: true` per richiedere il richiamo manuale. Per richiedere il richiamo manuale in Codex, crea `agents/openai.yaml` dentro la directory della skill:

```yaml
policy:
  allow_implicit_invocation: false
```

Il manifest è specifico del prodotto e separato dal frontmatter di `SKILL.md`; il [riferimento Codex](https://learn.chatgpt.com/docs/build-skills#optional-metadata) documenta questa policy. Lascia questa opzione fuori dal confronto delle descrizioni, che serve a osservare la selezione implicita. Anche `allowed-tools` in Claude riguarda la preapprovazione, non una sandbox che rende impossibili tutte le altre operazioni.

Per questa skill terrei la descrizione circoscritta e lascerei all’agente il giudizio sul diff e sui difetti. Il calcolo dello sconto e la soglia ammessa hanno già una risposta verificabile nel codice e nei test. Per decidere che cosa cambiare, userei le richieste salvate: la spiegazione che fa aprire la review porta a rivedere la descrizione; il test obbligatorio non eseguito porta a intervenire sul workflow. Aggiungerei criteri alla procedura quando il problema riguarda il modo in cui viene esaminato il diff.

Per il costo del contesto rimando alla [ricerca sui token di Claude e Codex](https://www.matteovincenti.com/blog/ridurre-token-claude-codex-esperimenti); per collegare dichiarazioni e prove, al [metodo di verifica degli agenti](https://www.matteovincenti.com/blog/allucinazioni-ai-verificare-agenti).