Skills

Le Skills sono il meccanismo principale per raggruppare e distribuire conoscenze di dominio agli agenti IA in CodeCourier. Ogni skill è una raccolta di file con un nome - documenti markdown, esempi di codice, riferimenti API, guide alle best practice - che vengono iniettati nella directory .claude/skills/ della sandbox prima dell’avvio dello strumento CLI. Quando un agente legge quei file, acquisisce conoscenza a livello esperto su una tecnologia o un’area di pratica specifica.

Le Skills supportano più file, il che significa che una singola skill può contenere una base di conoscenza completa e multi-documento invece di un singolo file monolitico. Ogni skill è versionata in modo indipendente, permettendoti di aggiornare le conoscenze di dominio senza toccare le skill non correlate.

Cosa sono le Skills

Pensa alle skill come alla biblioteca che consegni a un agente IA quando si mette al lavoro. Invece di sperare che i dati di addestramento dell’agente contengano i pattern giusti per il tuo stack specifico, fornisci materiale di riferimento curato, accurato e aggiornato all’inizio della sessione.

Esempi di skill e cosa contengono:

Modello dati delle Skills

Le skill sono memorizzate in tre tabelle correlate nel database:

// Core skill record
skills: {
  skillId: string       // unique identifier
  name: string          // display name (e.g., "frontend-design")
  description: string   // what this skill does and when to use it
  category: string      // grouping (e.g., "frontend", "testing", "backend", "security")
  fileCount: number     // number of files in the active version of this skill
  isEnabled: boolean    // whether this skill is selectable in the UI
}

// Individual files within a skill
skillFiles: {
  skillId: string
  path: string          // file path within the skill directory (e.g., "patterns.md")
  content: string       // full file content (markdown or code)
}

// Version history
skillVersions: {
  skillId: string
  version: number       // incrementing version number
  name: string          // name at time of publish
  description: string   // description at time of publish
  category: string      // category at time of publish
  fileCount: number     // number of files in this version
  status: "active" | "inactive"
  publishedAt: number   // Unix timestamp
  publishedBy: string   // user ID of publisher
}

Creare una skill personalizzata

Le skill personalizzate vengono create dalla pagina di gestione delle Skills. Vai alla sezione skill del tuo progetto oppure accedi alla libreria globale delle skill dalle impostazioni della piattaforma.

# Convex Query Patterns

## Reading Data
Always use `useQuery` for reactive data subscriptions in React components.
Use `ctx.db.query` inside Convex server functions.

### Pagination
Never use `.collect()` on large tables. Use `.paginate()` instead:
```ts
const results = await ctx.db
  .query("posts")
  .order("desc")
  .paginate(opts); // opts.numItems controls page size
```

## Writing Data
All data mutations must go through Convex mutation functions.
Never write directly to the database from client code.

### Scheduling Background Work
Heavy operations go to `ctx.scheduler.runAfter` to avoid timeout:
```ts
await ctx.scheduler.runAfter(0, internal.tasks.processLargeDataset, {
  datasetId: args.datasetId,
});
```

## Validators
Use Convex's built-in validators for all mutation and action arguments.
Do NOT use Zod inside Convex functions.

Best practice per l’organizzazione dei file di skill

Il modo in cui organizzi i file all’interno di una skill influisce sulla facilità con cui un agente può navigare tra le conoscenze. Segui queste linee guida:

• Un argomento per file - Un overview.md per i concetti di alto livello, un patterns.md per i pattern di codice, un anti-patterns.md per le cose da evitare e un api-reference.md per le API specifiche. Questo rende ogni file scorribile senza sovraccaricare il contesto.
• Inizia con le regole più importanti - Gli agenti leggono i file in modo sequenziale. Metti i vincoli più critici all’inizio di ogni file, non nascosti nel mezzo.
• Usa esempi di codice concreti - Le spiegazioni in markdown sono utili, ma gli snippet di codice che mostrano l’uso corretto e scorretto sono ancora più efficaci.
• Mantieni i singoli file sotto le 500 righe - I file molto lunghi sono più difficili da elaborare in modo efficace per gli agenti. Suddividi i grandi documenti di riferimento in più file focalizzati.
• Nomina i file per la reperibilità - Usa nomi come quick-reference.md, gotchas.md, examples.md in modo che l’agente possa dedurre lo scopo del file dal solo nome.

Versionare le Skills

Le skill seguono lo stesso ciclo di vita di versionamento dei Context Document. Modificare i file di una skill crea una bozza. La pubblicazione crea una nuova versione, la attiva e disattiva la versione precedente.

Scenari chiave che dovrebbero attivare una nuova versione di skill:

• Una libreria rilascia una versione major con modifiche API che rompono la compatibilità
• Il tuo team adotta una nuova convenzione di codifica che gli agenti devono seguire
• Un agente ha commesso un errore sistematico che può essere prevenuto con una nuova regola nella skill
• Scopri che un pattern esistente nella skill è obsoleto o errato

Assegnare le Skills alle personas

Per assegnare le skill a una persona, vai alla pagina di dettaglio della persona e apri la scheda Skills. La scheda mostra tutte le skill abilitate nel progetto organizzate in tre sezioni:

• Skills - I pacchetti di skill descritti in questa guida
• Commands - Estensioni slash-command di Claude Code
• Scripts - Script shell/Python eseguibili

Seleziona le caselle accanto a ogni skill che vuoi rendere disponibile per questa persona. Le selezioni vengono salvate immediatamente e si applicano a tutte le sessioni eseguite da questa persona da quel momento in poi.

Assegnare le Skills ai tipi di sessione

Le assegnazioni predefinite di skill per ciascun tipo di sessione sono configurate nella corrispondente scheda di configurazione all’interno delle Impostazioni del progetto. Ad esempio, per configurare le skill predefinite per tutte le sessioni di Issue Discovery, vai a /p/{id}/issues-setup e seleziona le skill desiderate dalle sezioni Skills, Commands e Scripts di quella pagina.

Queste impostazioni predefinite del tipo di sessione si applicano a qualsiasi sessione di quel tipo in cui la persona in esecuzione non ha proprie selezioni esplicite di skill.

Abilitare e disabilitare le Skills

Le skill hanno un flag isEnabled. Le skill disabilitate non compaiono nelle caselle di selezione nelle schede Skills delle persona né nelle Impostazioni del progetto. Questo è utile per le skill in fase di sviluppo o che vuoi nascondere temporaneamente dall’interfaccia di selezione senza eliminarle.

Disabilitare una skill non la rimuove dalle sandbox a cui era già stata assegnata - le assegnazioni esistenti vengono preservate. La disabilitazione impedisce solo alla skill di comparire come opzione selezionabile per le nuove assegnazioni.

Prossimi passi