Guida pratica a Codex Skills e Plugins: rendere riutilizzabili i workflow del team

La stessa checklist di code review viene copiata in cinque repository. A ogni PR bisogna ancora ricordare a mano: “prima rilancia i test falliti”, “controlla il confine dei permessi”, “non dimenticare il changelog”. Il problema non è che il prompt sia troppo corto. Il processo non è ancora diventato una capacità riutilizzabile.

Codex Skills e Plugins servono proprio a risolvere questa ripetizione: portano i workflow ricorrenti del team fuori dai prompt usa e getta e da un AGENTS.md sempre più lungo, trasformandoli in capacità riutilizzabili. Uno Skill è il formato per scrivere un workflow riutilizzabile. Un Plugin è un’unità installabile di distribuzione. Non sostituiscono le regole di progetto: le regole permanenti restano in AGENTS.md; procedure in più passaggi, esempi, script e riferimenti lunghi vanno negli Skills; la distribuzione al team diventa un Plugin.

Una tabella decisionale basta per scegliere tra Skill, Plugin, MCP, AGENTS.md e Subagent. Da lì puoi partire da un albero Skill minimo e arrivare alla scomposizione di un role-specific plugin, alla distribuzione nel team e alla checklist dei confini di permesso.

1. Workflow di team copiati: il problema non è il prompt

Code review, controlli prima della release, flussi di test e aggiornamenti della documentazione hanno spesso una forma fissa nel team. Potresti già incollare in Codex, a ogni PR review, un prompt come: “controlla se manca il changelog, se la copertura dei test è scesa e se bisogna aggiornare la documentazione API”. I problemi emergono subito:

• La manutenzione è sparsa: quando cambia la checklist, devi aggiornare cinque .github/PULL_REQUEST_TEMPLATE.md o file prompt separati.
• La qualità di esecuzione non è stabile: Codex deve capire il processo da zero ogni volta e può saltare passaggi importanti come “rilancia prima i test falliti”.
• I confini di ruolo si confondono: frontend, QA, sicurezza e documentazione finiscono nello stesso prompt, quindi Codex fatica a capire quale standard applicare.

Alcuni team mettono tutto in AGENTS.md, ma così nasce un altro problema: il file delle regole progetto diventa sempre più lungo. Comandi di build permanenti, convenzioni di directory e istruzioni temporanee di processo si mescolano. Il file supera il suo compito originale di contenere vincoli di progetto duraturi.

Codex permette una divisione più chiara: AGENTS.md per regole permanenti, Skills per workflow riutilizzabili, Plugins per distribuzione. Il punto è capire cosa mettere in ogni livello.

2. Una tabella per distinguere Skill, Plugin, MCP e AGENTS.md

Uno Skill è un formato di autore per workflow riutilizzabili, di solito un file SKILL.md con scripts, references e assets opzionali. Un Plugin è un’unità installabile di Codex che può impacchettare Skills, app integrations, MCP servers e assets. MCP è il protocollo per collegare strumenti esterni e contesto, come documentazione di terze parti, browser, Figma o GitHub. AGENTS.md contiene vincoli permanenti di progetto: comandi di build, convenzioni di directory, aspettative di review. Un Subagent delega un ruolo per task rumorosi o specializzati.

Quando scegliere ogni opzione

Tipo di contenuto	Opzione adatta	Scenario tipico	Da evitare per
Comandi di build, percorsi di script test, convenzioni di directory	AGENTS.md	”Tutti i nuovi componenti vanno in src/components/”, “i test si lanciano con npm run test:unit”	Processi in più passaggi, esempi, chiamate a strumenti esterni
Workflow in più passaggi con esempi, script o riferimenti	Skill	Code review in 10 passaggi, checklist di release in 7 punti, generazione docs API	Una sola regola o un singolo comando
Distribuzione di team e packaging di configurazione app/MCP	Plugin	Plugin di ruolo frontend con 4 Skills di review e Figma connector	Workflow iterato in un solo repository e senza bisogno di condivisione
Chiamate a strumenti esterni e contesto di terze parti	MCP	Recuperare specifiche Figma, leggere issue via GitHub API	Definizione pura di workflow senza dati esterni
Delega di task rumorosi o specializzati	Subagent	Far gestire diagnosi test o analisi log a un agent dedicato	Procedure semplici gestibili nella conversazione principale

Quando spostare qualcosa da AGENTS.md a uno Skill

Questi segnali indicano che il processo ha superato il ruolo del file di regole progetto e dovrebbe diventare uno Skill:

• La stessa checklist ricorre in più PR e viene incollata ogni volta.
• Il processo ha più passaggi e richiede esempi, script o riferimenti esterni.
• Il processo ha un trigger chiaro, come “prima della release” o “durante la pull request review”, invece di essere un vincolo permanente.
• Ruoli diversi hanno standard diversi e non conviene metterli tutti in un unico file.
• Servono versionamento e note di modifica, non l’ennesima modifica diretta alle regole di progetto.

Quando passare da Skill a Plugin

Uno Skill basta mentre lo stai iterando in un repository o in un workflow personale. Passa a un Plugin quando hai bisogno di:

• condivisione tra team, non solo in una directory personale o in un singolo repository;
• packaging di app integrations, come Figma, GitHub, strumenti CI/CD, o configurazione MCP server;
• versionamento, changelog e meccanismo di upgrade, invece di copiare cartelle Skill;
• distribuzione tramite Plugin Directory di Codex App ai workspace members;
• un pacchetto stabile, non un workflow sperimentale che cambia di continuo.

Un ordine pratico: fissa le convenzioni del repository in AGENTS.md; installa un Plugin esistente se fa al caso tuo; altrimenti crea uno Skill; trasformalo in Plugin quando serve davvero distribuirlo; aggiungi MCP solo quando serve un sistema esterno; usa Subagent quando il task è abbastanza rumoroso o specializzato da meritare delega.

3. Skill minimo utile: partire dalla code review

Albero minimo di uno Skill

Uno Skill ha bisogno almeno di questa struttura:

.agents/skills/code-review/
├── SKILL.md
├── references/
│   └── security-checklist.md
└── scripts/
    └── run-failed-tests.sh

Il nome della directory e il campo name nel frontmatter di SKILL.md devono coincidere. Il formato è lowercase alphanumeric + hyphen.

Esempio di SKILL.md: Skill di code review

---
name: code-review
description: Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs. Do not use for backend-only changes or infrastructure PRs.
---

# Code Review Checklist

## Before Starting
1. Run failed tests first: `npm run test:failed`
2. Check if PR has clear description and scope

## Review Steps
1. Changelog: Does `CHANGELOG.md` need update?
2. Test Coverage: Did coverage decrease? Check report in `coverage/`
3. Security: Review changes in `src/auth/`, `src/api/`, and `src/middleware/`
4. API Docs: If API changed, update `docs/api.md`

## Security Boundary Checks
See `references/security-checklist.md` for detailed items.

## Failed Test Runner
Use `scripts/run-failed-tests.sh` to rerun previously failed tests.

Progettare il trigger nella description: before/after

Codex usa la description per decidere se richiamare implicitamente uno Skill. Se è troppo vaga, può attivarsi troppo spesso o non attivarsi affatto:

Before, facile da attivare male	After, più affidabile
”Code review skill for frontend projects"	"Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs."
"Help review code"	"Use when reviewing PRs with frontend changes. Do not use for backend-only changes or infrastructure PRs."
"Review checklist"	"Trigger on: PR reviews, code audit requests. Exclude: backend changes, config-only updates.”

Scrivi confini chiari con “Use when…” e “Do not use when…”. Metti parole trigger come pull request, review e frontend nella prima metà. Le description lunghe possono essere tagliate. Se vuoi solo invocazione esplicita, imposta allow_implicit_invocation: false.

Posizione e ambito degli Skills

Posizione	Ambito	Caso d’uso	Note
.agents/skills/ nella root del repository	Repository corrente	Processi di review, test e release del team	Da committare in Git e condividere
$HOME/.agents/skills/	Personale, multi-progetto	Stile personale e comandi frequenti	Non viene sincronizzato automaticamente nel repository
/etc/codex/skills/	Organizzazione	Review sicurezza o compliance comuni	Richiede permessi admin
System bundled	Integrato	Skills come $skill-creator, $skill-installer	Non modificabile

Gli Skills con lo stesso nome non vengono fusi. La priorità di solito è repo > user > admin > system, ma la documentazione ufficiale resta la fonte se il comportamento cambia.

Progettare la progressive disclosure

Non mettere tutto nel SKILL.md principale. Codex usa progressive disclosure in tre livelli:

1. Metadata: all’inizio vede solo name, description e file path.
2. Instructions: il SKILL.md completo viene caricato solo dopo la selezione dello Skill.
3. Resources: references/, scripts/ e assets/ vengono letti solo quando servono.

Come regola, tieni il SKILL.md principale sotto le 500 righe. I riferimenti lunghi vanno in file separati. scripts/ dovrebbe contenere controlli deterministici, come test runner o verifica della copertura. references/ ospita checklist dettagliate, documenti di contesto e casi storici. assets/ va bene per template e screenshot di esempio.

Invocazione esplicita e implicita

L’invocazione esplicita usa $code-review o il selettore /skills. L’invocazione implicita lascia a Codex la scelta, in base alla description, se lo Skill è adatto al task corrente. Per disattivarla, imposta allow_implicit_invocation: false in agents/openai.yaml.

L’invocazione implicita funziona bene per workflow frequenti e con confini chiari, come la review di ogni PR. L’invocazione esplicita è più sicura per lavori rari che richiedono giudizio, come un audit sicurezza trimestrale. Se uno Skill include script esterni o operazioni sensibili, preferisci l’invocazione esplicita.

4. Packaging Plugin e distribuzione di team: dallo Skill locale alla suite del team

Struttura minima di un Plugin

Un Plugin non è solo una cartella Skill rinominata. È un pacchetto installabile e richiede almeno un manifest .codex-plugin/plugin.json:

.agents/plugins/frontend-review/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── accessibility-check/
│   │   └── SKILL.md
│   └── performance-lint/
│       └── SKILL.md
├── assets/
│   └── templates/
└── README.md

Campi obbligatori di plugin.json

{
  "name": "frontend-review",
  "version": "1.0.0",
  "description": "Frontend team code review and accessibility check skills",
  "skills": "./skills/",
  "assets": "./assets/",
  "author": "frontend-team",
  "repository": "https://github.com/org/frontend-review-plugin"
}

I campi opzionali includono apps per app integrations come .app.json for Figma, mcpServers per configurazione MCP server come .mcp.json, e policy per permessi e condivisione dati, sempre soggetti alla workspace admin policy.

Struttura marketplace: directory dei Plugin del team

Un Plugin marketplace è un elenco JSON che punta ai percorsi dei Plugin:

.agents/plugins/marketplace.json

{
  "plugins": [
    {
      "source": "local",
      "path": "./frontend-review"
    },
    {
      "source": "github",
      "owner": "openai",
      "repo": "role-specific-plugins",
      "ref": "main",
      "path": "plugins/data-analytics"
    }
  ]
}

local è adatto ai Plugin interni non ancora pubblicati. github punta a repository pubblici o pacchetti condivisi tra team.

Checklist dei comandi per distribuire Plugin

I comandi CLI possono cambiare, quindi usa la documentazione ufficiale come riferimento:

# Scaffold di un nuovo Plugin
codex plugin create frontend-review

# Aggiungere un Plugin al marketplace
codex plugin marketplace add owner/repo --ref main --sparse

# Elencare i Plugin installati
codex plugin marketplace list

# Aggiornare un Plugin
codex plugin marketplace upgrade frontend-review

# Rimuovere un Plugin
codex plugin marketplace remove frontend-review

In Codex App, Plugin Directory può mostrare Curated by OpenAI, Shared with you e Created by you. Un local plugin può essere condiviso con workspace members o groups. Gli workspace admins possono disattivare plugin sharing o impostare managed requirements.

Condividere nel workspace non significa pubblicare. Le connessioni ad app esterne e MCP servers richiedono ancora autorizzazione, e gli approval settings continuano a valere.

Organizzare il marketplace del team

Metti il marketplace del repository in $REPO_ROOT/.agents/plugins/marketplace.json per Plugin specifici del progetto. Per Plugin di organizzazione, usa $HOME/.agents/plugins/marketplace.json o un repository GitHub organization. La versione va dichiarata nel manifest con version. Il README mantiene il changelog, e gli upgrade si validano in un ambiente di test. Plugin sensibili, come sicurezza o compliance, stanno meglio a livello organizzazione, così non vengono installati casualmente.

Parti da local skill, iteralo, poi impacchettalo come Plugin quando è stabile. Creare subito il Plugin di solito rende più difficile cambiare il workflow.

5. Disegno di role-specific Plugin: fissare frontend, QA e documentazione

Il repository role-specific-plugins di OpenAI fornisce template per Sales, Data Analytics, Product Design e Financial Markets. Un team di sviluppo non deve copiare workflow sales o finance. Però il metodo di scomposizione è utile: parti da un ruolo, estrai 3-5 piccoli Skills e impacchettali in un Plugin.

Schema di scomposizione: ruolo → output ricorrenti → fonti dati/strumenti → piccoli Skills → modello di condivisione

Ruolo	Output ricorrenti	Fonti dati/strumenti	Skills da estrarre	Apps/MCP possibili	Criterio di accettazione
Ingegnere frontend	Revisione componenti, controllo performance, validazione accessibilità	Specifiche Figma, libreria Storybook esistente	component-audit, accessibility-check, performance-lint, design-system-sync	Figma connector, Storybook MCP	Ogni nuovo componente passa tutti e 4 i controlli
Ingegnere QA	Report copertura, diagnosi suite E2E, checklist regressione	Risultati CI/CD, storico fallimenti	test-coverage-check, e2e-suite-runner, flaky-test-diagnosis, regression-suite-builder	Strumenti CI/CD come GitHub Actions/Jenkins	Test falliti prima, copertura non in calo
Technical writer	Aggiornamento API docs, changelog, guide migrazione	API schema, Git commit history	api-doc-generator, changelog-builder, readme-audit, migration-guide-writer	GitHub API, strumenti schema	Documentazione aggiornata quando cambia l’API
Ingegnere sicurezza	Review confini permessi, secrets scan, sicurezza dipendenze	Manifest dipendenze, configurazione secrets	auth-boundary-check, secrets-scan, dependency-security	Snyk, Dependabot MCP	Checklist sicurezza completata prima di ogni release

Esempio di scomposizione per Plugin ruolo frontend

frontend-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── component-audit/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── component-template.md
│   ├── accessibility-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── axe-audit.sh
│   ├── performance-lint/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── lighthouse-check.sh
│   └── design-system-sync/
│       ├── SKILL.md
│       └── references/
│           └── design-tokens.md
├── assets/
│   └── templates/
│       └── component-template.tsx
└── README.md

component-audit controlla se un nuovo componente segue le regole del team, per esempio naming, directory e tipi delle props. accessibility-check esegue uno script axe-core. performance-lint controlla le metriche principali con Lighthouse. design-system-sync confronta l’implementazione con le specifiche Figma.

Esempio di scomposizione per Plugin ruolo QA

qa-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── test-coverage-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── coverage-threshold-check.sh
│   ├── e2e-suite-runner/
│   │   └── SKILL.md
│   ├── flaky-test-diagnosis/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── flaky-test-log-analysis.md
│   └── regression-suite-builder/
│       └── SKILL.md
├── .mcp.json
└── README.md

test-coverage-check rileva se la copertura scende e segnala i file non coperti. e2e-suite-runner esegue i test E2E per priorità. flaky-test-diagnosis analizza gli storici di fallimento per trovare test instabili. regression-suite-builder costruisce una checklist di regressione in base alla superficie modificata.

Checklist per sostituire connector placeholder

I template ufficiali possono contenere placeholder connector id in .app.json. Vanno sostituiti prima dell’installazione:

{
  "app_id": "figma-placeholder"
}

Controlla tutti i placeholder id in .app.json e sostituiscili con ID reali disponibili nel workspace di destinazione. Non copiare connector id da altri workspace: potrebbero essere non validi o senza permessi. Anche OAuth/Bearer token nelle impostazioni MCP server devono essere configurati per il tuo ambiente, non copiati dagli esempi. Dopo la sostituzione, valida il connector in un ambiente di test.

Il README ufficiale di role-specific-plugins indica che questi template Plugin sono pensati per essere personalizzati prima dell’uso. I connector-backed plugins possono contenere app ID o connector ID da sostituire.

6. Sicurezza e manutenzione: un Plugin non è un pass per i permessi

Confini di permesso per Connector / MCP

Installare un Plugin non aggira gli approval settings di Codex. App esterne e MCP servers richiedono ancora autorizzazione, e la condivisione dei dati resta soggetta alle rispettive policy. I placeholder id in .app.json vanno sostituiti, ma non devi copiare connector id da altri workspace. App esterne come Figma o GitHub richiedono autorizzazione separata. Il Plugin impacchetta configurazione, non autorizza al posto tuo. Gli MCP server restano controllabili in config.toml tramite enabled e tool policy. Anche Approval mode continua a valere: se è impostato su “suggest-only”, gli script nel Plugin non vengono eseguiti automaticamente.

Non trattare un Plugin come un pass per i permessi. Impacchetta workflow, configurazione e assets, ma il confine di permesso resta.

Verifica della fonte degli script

La directory scripts/ dentro uno Skill o Plugin può contenere file eseguibili. Plugin di terze parti e marketplace di community richiedono revisione: controlla tutti gli eseguibili in scripts, conferma la fonte, evita di eseguire script da repository non verificati, prova prima in ambiente di test e blocca le versioni con tag o commit hash invece di tirare sempre da main.

Lo stesso principio usato per Skills di terze parti rischiosi vale per qualunque script eseguibile e Plugin esterno: verifica la fonte, riduci i permessi, valida in ambiente di test.

Versioni e changelog

La collaborazione in team richiede versionamento. Metti un campo version chiaro in plugin.json e incrementalo a ogni aggiornamento. Nel README mantieni un changelog che spiega quali Skills sono stati aggiunti, modificati o deprecati. Prima di aggiornare, prova in ambiente di test, esegui tutti gli Skills, verifica che gli script funzionino e conferma che i connector siano ancora disponibili. Nel marketplace, usa ref fissato a tag o commit, non il main più recente ogni volta.

Impatto del numero di Skills e Plugins

La lista iniziale degli Skills ha un budget di contesto. La documentazione ufficiale indica che la initial skills list occupa circa il 2% del contesto, oppure 8.000 characters quando la dimensione del contesto è sconosciuta.

In pratica, una Skill description troppo lunga può essere tagliata, quindi le parole trigger devono stare all’inizio. Caricare troppi Skills può anche rendere più difficile per Codex scegliere quello giusto. Gli Skills frequenti e con confini chiari stanno bene in una directory repo o user. Gli Skills rari stanno meglio in un Plugin da installare al bisogno, invece che sempre presenti.

Se Codex attiva spesso lo Skill sbagliato o non attiva quello giusto, controlla prima la description. Aggiungere altri Skills raramente risolve il problema.

7. Confronto con tecnologie correlate

Confronto con Claude Code Skills

BetterLink ha già spiegato il meccanismo di Claude Code Skill. Il modello mentale è simile, ma i prodotti sono diversi: entrambi usano il formato aperto Agent Skills e un file SKILL.md; entrambi usano name, description e opzionalmente scripts/, references/, assets/; entrambi supportano progressive disclosure: metadata → instructions → resources.

Le differenze contano. Codex usa .agents/skills/; Claude Code usa .claude/skills/. Codex si invoca con $skill-name o /skills; Claude Code usa il comando /skill. Per la distribuzione, Codex Plugin ha marketplace, comandi CLI e workspace sharing; Claude Code non ha oggi un Plugin marketplace ufficiale. Anche gli strumenti integrati cambiano: Codex ha $skill-creator, $skill-installer, @plugin-creator; Claude Code ha comandi propri.

Se hai già scritto Claude Code Skills, puoi riusare il modello mentale. Non copiare però percorsi e sintassi di chiamata: segui la documentazione ufficiale di ciascun prodotto.

Come si divide con MCP

MCP, Model Context Protocol, collega strumenti esterni e contesto. Non sostituisce Skills o Plugins. Uno Skill definisce il workflow. MCP collega lo strumento esterno, come Figma, GitHub o un sistema CI/CD. Un Plugin può impacchettare la configurazione MCP server, ma l’MCP server resta controllato da config.toml.

Esempio: uno Skill di review frontend definisce il processo per controllare se un componente rispetta il design system. Un Figma MCP server fornisce accesso al file di design. Un Plugin frontend impacchetta Skill di review e configurazione Figma MCP, ma Figma OAuth richiede comunque autorizzazione separata.

Qui chiarisco solo il confine. Una guida pratica dedicata a Codex MCP tools può approfondire l’implementazione.

Conclusione

Codex Skills e Plugins servono a togliere i workflow ripetuti del team da prompt copiati e da un AGENTS.md sovraccarico, lasciandoli come capacità riutilizzabili. La regola è semplice: AGENTS.md per regole permanenti, Skill per workflow in più passaggi, Plugin per packaging e distribuzione, MCP per sistemi esterni. Scrivi condizioni di trigger chiare nella description, valida prima un local skill e trasformalo in Plugin solo quando la distribuzione è reale. Scripts, connector id e configurazioni MCP di Plugin di terze parti vanno comunque verificati.

Parti da uno Skill minimo. Trasforma il processo di code review o test del team in SKILL.md, eseguilo alcune volte e verifica se il trigger è affidabile. Se il team ha ruoli frontend, QA, sicurezza o documentazione, usa il pattern di OpenAI role-specific-plugins: 3-5 piccoli Skills per ruolo, poi un Plugin di ruolo.

Letture correlate su BetterLink:

• Guida completa per iniziare con Codex
• Regole di progetto AGENTS.md
• Confini di sicurezza e gestione dei permessi in Codex
• Codex MCP tools in pratica
• Confronto con Claude Code Skill
• Basi del protocollo MCP