coding agent Pi

Indice

1. Perché Pi non è il solito coding agent
2. Context Files: la tua base di conoscenza permanente
3. Prompt Templates: non riscrivere mai più lo stesso prompt
4. Skills: competenze specializzate on-demand
5. Extensions: il vero salto di qualità
6. Pi Packages: condividere le personalizzazioni
7. Strategia di integrazione: da zero a un ecosistema completo
8. Best practices e workflow quotidiani
9. Riepilogo e percorso di adozione

1. Perché Pi non è il solito coding agent

Per molto tempo abbiamo pensato che un coding agent dovesse fare tutto: sub-agents, plan mode, MCP, todo list integrate, popup di conferma, integrazioni preconfezionate. La logica sembrava semplice: più funzionalità built-in, più lo strumento sarebbe stato utile.

Poi è arrivato Pi.

Coding agent Pi terminal-first, open source (licenza MIT), costruito da Earendil Inc. con una filosofia quasi controcorrente. Parte essenziale: solo quattro tool predefiniti — read, write, edit, bash. Niente sub-agents. Niente plan mode. Niente popup. Niente MCP nativo.

A prima vista potrebbe sembrare povero. In realtà è esattamente il contrario.

Il ragionamento dietro Pi è questo: ogni sviluppatore ha preferenze, stack, workflow diversi. Imporre un unico modo di lavorare significa forzare tutti dentro lo stesso schema. Invece di aggiungere funzionalità preconfezionate, Pi ti dà quattro meccanismi di estensione per costruire esattamente ciò di cui hai bisogno, quando ne hai bisogno.

Non è un prodotto chiuso da subire. È un toolkit da modellare.

E la cosa più interessante è che questi meccanismi coprono l’intero spettro di complessità: si parte da due righe di Markdown e si arriva a moduli TypeScript completi. Puoi iniziare in dieci minuti e crescere per mesi.

Osserviamo questi meccanismi uno per uno.

2. Context Files: la tua base di conoscenza permanente

Immagina di assumere un nuovo sviluppatore nel tuo team. Il primo giorno gli daresti accesso al codice e lo lasceresti indovinare le convenzioni? Probabilmente no. Gli daresti un documento, una guida, delle regole.

Con Pi funziona allo stesso modo. I Context Files sono file Markdown — AGENTS.md o CLAUDE.md — che Pi carica automaticamente all’avvio e concatena nel suo system prompt. In pratica, sono le istruzioni permanenti che l’agente non dimentica mai.

Dove metterli

Pi cerca questi file in tre punti, e li concatena tutti in ordine:

1. ~/.pi/agent/AGENTS.md — istruzioni globali, valide per ogni progetto su cui lavori
2. Directory antenate — risalendo dalla working directory fino alla root del filesystem
3. Directory corrente — il progetto specifico su cui stai lavorando

Questo significa che puoi avere convenzioni personali globali, convenzioni di organizzazione (in un monorepo, per esempio) e convenzioni specifiche del progetto, tutte attive contemporaneamente. È un sistema a strati che si somma senza conflitti.

Cosa scrivere dentro un AGENTS.md

La domanda non è “cosa posso metterci” ma “cosa voglio che l’agente sappia sempre”. Ecco un esempio concreto per un progetto React con TypeScript e Tailwind:

# AGENTS.md — Progetto Dashboard

## Stack
- Frontend: Next.js 15, TypeScript strict, Tailwind CSS
- Backend: Fastify, PostgreSQL, Prisma
- Testing: Vitest + Playwright

## Convenzioni
- PascalCase per i componenti React, camelCase per funzioni e variabili
- Ogni file esporta al massimo un componente principale
- NO CSS modules — solo Tailwind
- I test vivono in `__tests__/` accanto al file sorgente
- React 19 hooks pattern, NO class components

## Comandi
- `npm run dev` — avvia il server di sviluppo
- `npm run test -- --watch` — test in watch mode
- `npm run lint` — ESLint + Prettier

## Regole
- Non modificare MAI i file in `src/generated/`
- Prima di creare un nuovo componente, controlla se ne esiste già uno simile
- Per le chiamate API, usa l'hook `useApi` da `@/hooks/useApi`
- Per lo stato globale, preferisci Zustand a Redux
- Per le form, React Hook Form con validazione Zod

## Setup
- Node.js >= 20
- Database di sviluppo: `docker compose up -d db`

Non è codice. Non è configurazione complessa. È solo Markdown. Ma è il singolo strumento con il più alto rapporto costo/beneficio di tutto l’ecosistema Pi. In dieci minuti di scrittura ottieni un assistente che conosce le tue convenzioni e non le viola mai.

System Prompt personalizzato

Oltre ad AGENTS.md, puoi intervenire direttamente sul system prompt:

• ~/.pi/agent/SYSTEM.md o .pi/SYSTEM.md — sostituisce completamente il prompt di sistema predefinito
• ~/.pi/agent/APPEND_SYSTEM.md o .pi/APPEND_SYSTEM.md — accoda al prompt esistente senza sostituirlo

La differenza è importante: il primo ti dà controllo totale, il secondo aggiunge istruzioni senza perdere quelle di default.

Disabilitare i context file

Se per qualsiasi motivo vuoi avviare Pi senza caricare i context file:

pi --no-context-files    # oppure -nc

💡 Consiglio pratico: Inizia sempre da AGENTS.md. È lo strumento più semplice, più immediato e più potente. Prima di esplorare skill, extension o template, scrivi un buon file di contesto per il tuo progetto. Tutto il resto viene dopo.

3. Prompt Templates: non riscrivere mai più lo stesso prompt

C’è un momento preciso in cui ti rendi conto di aver bisogno dei template: la terza volta che scrivi lo stesso prompt, con leggere variazioni, per la terza volta nella stessa settimana.

I Prompt Templates sono file Markdown che si espandono in prompt completi quando digiti /nome nell’editor di Pi. Il nome del file diventa il comando: review.md diventa /review, test.md diventa /test.

Dove metterli

• ~/.pi/agent/prompts/*.md — disponibili in tutti i progetti
• .pi/prompts/*.md — specifici del progetto corrente

Anatomia di un template

---
description: Code review completa con focus su sicurezza e performance
argument-hint: "[area di focus]"
---

Esegui una code review approfondita del codice. Concentrati su:

## Cosa controllare
- Bug logici e casi limite non gestiti
- Vulnerabilità di sicurezza (XSS, SQL injection, path traversal)
- Problemi di performance (N+1 queries, rendering non necessario)
- Gestione errori mancante o insufficiente
- Race conditions e problemi di concorrenza
- Memory leak e risorse non rilasciate

Area di focus specifica: $1

Il frontmatter YAML non è decorativo: description e argument-hint appaiono nell’autocomplete quando premi /, rendendo i template scopribili senza dover ricordare i nomi.

Argomenti dinamici

I template supportano variabili posizionali che rendono ogni invocazione diversa:

Un esempio concreto: generatore di componenti React

---
description: Crea un componente React con test, TypeScript e Tailwind
argument-hint: "<NomeComponente> [props...]"
---

Crea un componente React con le seguenti specifiche:

- Nome: $1
- Props: $@
- File: `src/components/$1/$1.tsx`
- Test: `src/components/$1/__tests__/$1.test.tsx`
- Stili: Tailwind CSS
- Linguaggio: TypeScript strict
- Esporta come default

Uso: /component Button "onClick: () => void" "disabled?: boolean".

Un template più specializzato potrebbe coprire un audit di sicurezza:

---
description: Analisi completa delle vulnerabilità OWASP Top 10
---

## Security Audit — OWASP Top 10

Analizza il codice per ciascuna delle seguenti categorie:

1. **Broken Access Control** — autorizzazioni mancanti o bypassabili
2. **Cryptographic Failures** — dati sensibili esposti, hash deboli, cifratura assente
3. **Injection** — SQL, NoSQL, OS command injection
4. **Insecure Design** — rate limiting assente, errori di architettura
5. **Security Misconfiguration** — header HTTP, CORS, debug in produzione
6. **Vulnerable Components** — dipendenze con CVE note
7. **Auth Failures** — gestione password, sessioni, MFA
8. **Software & Data Integrity** — CI/CD, aggiornamenti non firmati
9. **Logging & Monitoring** — audit trail, log carenti
10. **SSRF** — richieste lato server non validate

Output: tabella con vulnerabilità, severity, descrizione, file:riga, remediation.

Uso: /security-audit — nessun argomento necessario, il template fa tutto.

💡 Consiglio pratico: Crea template per ogni task che ripeti più di due volte a settimana. Review, generazione di test, commit message, documentazione, refactoring. L’investimento iniziale di 5 minuti per template si ripaga nel giro di pochi giorni.

4. Skills: competenze specializzate on-demand

Fin qui abbiamo parlato di file statici: Markdown che viene caricato e punto. Le Skills introducono un concetto diverso: la progressive disclosure.

Immagina di avere un manuale di 200 pagine. Non lo leggeresti tutto ogni volta che devi usare un trapano. Lo apriresti solo quando ti serve la sezione sul trapano. Le skills funzionano proprio così.

Come funzionano

Le Skills implementano lo standard Agent Skills e sono pacchetti autocontenuti che Pi carica solo quando servono. All’avvio, Pi scansiona le directory di skills ed estrae nomi e descrizioni. Solo queste informazioni finiscono nel system prompt. Quando un task matcha la descrizione di una skill, l’agente la carica completamente usando read, segue le istruzioni e usa i percorsi relativi per script e asset.

Il vantaggio è enorme: puoi avere decine di skills installate senza intasare il contesto. Solo quella che serve viene caricata.

Dove metterle

• ~/.pi/agent/skills/ — globali, disponibili per ogni progetto
• ~/.agents/skills/ — alternativa globale
• .pi/skills/ — specifiche del progetto
• .agents/skills/ — progetto più directory antenate (fino alla root git)

Struttura di una skill

api-generator/
├── SKILL.md              # Obbligatorio: frontmatter + istruzioni
├── scripts/              # Script helper
│   └── scaffold.sh
├── references/           # Documentazione di riferimento
│   └── openapi-guide.md
└── assets/               # Template e risorse statiche
    └── router-template.ts

Il file SKILL.md

---
name: api-generator
description: Genera endpoint API RESTful con validazione Zod, test e documentazione OpenAPI. Usa questa skill quando l'utente chiede di creare nuovi endpoint, router API, o documentazione Swagger.
---

# API Generator

## Setup iniziale (esegui una volta)

```bash
cd skills/api-generator && npm install

Workflow

1. Raccogliere requisiti

Chiedi all’utente: risorsa, operazioni CRUD desiderate, campi, regole di validazione, autenticazione.

2. Generare i file

src/
├── routes/{resource}.ts      # Router Express/Fastify
├── schemas/{resource}.ts     # Validazione Zod
├── controllers/{resource}.ts # Logica di business
└── __tests__/
    └── {resource}.test.ts    # Test

3. Struttura del router

Usa il template in assets/router-template.ts.

4. Documentazione OpenAPI

Genera sempre la documentazione Swagger come commenti JSDoc inline.

Convenzioni

• Validazione: sempre Zod
• Formato errori: { error: string, details?: any }
• Paginazione: cursor-based con nextCursor

### Il frontmatter delle skills

| Campo | Obbligatorio | Descrizione |
|-------|:---:|-------|
| `name` | Sì | Massimo 64 caratteri, minuscolo, lettere/numeri/hyphen |
| `description` | Sì | Massimo 1024 caratteri. È l'unica cosa che il modello vede per decidere se caricare la skill — scrivila con molta cura |
| `license` | No | Nome licenza o riferimento a file |
| `compatibility` | No | Requisiti d'ambiente (max 500 caratteri) |
| `metadata` | No | Mappa chiave-valore arbitraria |
| `allowed-tools` | No | Tool pre-approvati (funzionalità sperimentale) |
| `disable-model-invocation` | No | Se `true`, la skill è invisibile nel system prompt e si attiva solo con `/skill:nome` |

### Skill repository utili

La community ha già prodotto skill pronte all'uso:

- **[Anthropic Skills](https://github.com/anthropics/skills)** — elaborazione documenti (docx, pdf, pptx, xlsx)
- **[Pi Skills](https://github.com/badlogic/pi-skills)** — web search, browser automation, API Google

### Usare skill di altri harness

Se usi anche Claude Code o OpenAI Codex, puoi puntare alle stesse directory:

```json
{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

Questo si configura in ~/.pi/agent/settings.json.

Invocare una skill

Le skill possono essere attivate in due modi: automaticamente quando il modello riconosce un task pertinente, oppure manualmente:

/skill:api-generator                           # Carica ed esegui
/skill:brave-search "TypeScript decorators"     # Con argomenti

💡 Consiglio pratico: La descrizione nel frontmatter è la parte più importante di tutta la skill. È l’unica informazione che il modello usa per decidere se attivarla. Sii specifico su quando usarla e per cosa. Una descrizione vaga come “Aiuta con le API” non verrà mai attivata. Una descrizione come “Genera endpoint API RESTful con validazione Zod, test e documentazione OpenAPI. Usa questa skill quando l’utente chiede di creare nuovi endpoint, router API, o documentazione Swagger” sì.

5. Extensions: il vero salto di qualità

Fin qui abbiamo parlato di Markdown e YAML. Le Extensions sono il meccanismo che alza l’asticella: moduli TypeScript che estendono Pi a livello di codice, con accesso a tutto il ciclo di vita dell’agente.

È qui che Pi smette di essere un semplice coding agent e diventa una piattaforma programmabile.

Dove metterle

• ~/.pi/agent/extensions/*.ts — globali
• ~/.pi/agent/extensions/*/index.ts — globali in sottodirectory
• .pi/extensions/*.ts — specifiche del progetto

Cosa puoi costruire

Le possibilità sono ampie:

Anatomia di un’extension

Vediamo un esempio concreto. Questa extension fa tre cose: mostra un messaggio all’avvio, blocca comandi pericolosi e registra un tool per gestire una todo list:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  // 1. Messaggio di benvenuto all'avvio della sessione
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("🚀 Estensione caricata con successo!", "info");
  });

  // 2. Bloccare comandi bash pericolosi
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm(
        "⚠️ Comando pericoloso rilevato",
        "Sei assolutamente sicuro di voler eseguire rm -rf?"
      );
      if (!ok) return { block: true, reason: "Bloccato dall'utente" };
    }
  });

  // 3. Registrare un tool personalizzato
  pi.registerTool({
    name: "create_todo",
    label: "Create Todo",
    description: "Crea un nuovo task nella todo list del progetto",
    parameters: Type.Object({
      title: Type.String({ description: "Titolo del task" }),
      priority: Type.Optional(
        Type.String({ description: "Priorità: low, medium, high" })
      ),
    }),
    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
      const todo = {
        id: Date.now(),
        title: params.title,
        priority: params.priority ?? "medium",
        done: false
      };
      // In un'implementazione reale, qui salveresti su file o database
      return {
        content: [{
          type: "text",
          text: `✅ Task "${params.title}" creato con priorità ${params.priority ?? "medium"}.`
        }],
        details: { todo },
      };
    },
  });

  // 4. Registrare un comando slash
  pi.registerCommand("stats", {
    description: "Mostra statistiche del progetto corrente",
    handler: async (_args, ctx) => {
      ctx.ui.notify("📊 Statistiche in elaborazione...", "info");
      // Qui andrebbe la logica di raccolta statistiche
    },
  });
}

Il ciclo di vita degli eventi

Le extensions possono agganciarsi a questi eventi:

Avvio Pi
  │
  ├─► project_trust     — decisione sulla fiducia del progetto
  ├─► session_start     — sessione avviata
  └─► resources_discover — risorse scoperte

Invio prompt ──────────────────────────────────────┐
  │                                                │
  ├─► input              — intercetta/trasforma     │
  ├─► before_agent_start — modifica system prompt   │
  ├─► agent_start → agent_end                       │
  │                                                │
  │   ┌─── ciclo turno ──┐                         │
  │   │  turn_start       │                        │
  │   │  context (msg)    │                        │
  │   │  tool_call (blk)  │                        │
  │   │  tool_result (mod)│                        │
  │   │  turn_end         │                        │
  │   └──────────────────┘                         │
  └────────────────────────────────────────────────┘

Uscita → session_shutdown

Sicurezza: una nota importante

Le extensions girano con i tuoi pieni permessi di sistema. Non c’è sandbox. Non c’è isolamento. Per questo Pi chiede conferma prima di fidarsi di un progetto che contiene .pi/extensions/. Installa solo extensions da fonti fidate — la potenza di questo meccanismo è direttamente proporzionale alla responsabilità che richiede.

Modalità operative

Le extensions funzionano in tutte le modalità di Pi (interattiva, print, JSON, RPC), ma alcune funzionalità UI sono disponibili solo in TUI. Puoi verificare con:

if (ctx.mode === "tui" && ctx.hasUI) {
  // UI interattiva disponibile
}

💡 Consiglio pratico: La prima extension che tutti dovrebbero scrivere è un “gatekeeper”: intercetta tool_call per bash, blocca pattern pericolosi e chiede conferma per operazioni distruttive. Sono meno di venti righe di codice e possono salvarti da disastri.

6. Pi Packages: condividere le personalizzazioni

Dopo aver costruito la tua collezione di prompt template, skills ed extensions, arriva il momento di condividerla. I Pi Packages sono bundle che raggruppano tutte queste risorse e le distribuiscono via npm o git.

Installazione

# Da npm (con versione pinnata)
pi install npm:@acme/pi-tools
pi install npm:@acme/pi-tools@1.2.3

# Da GitHub (con tag o commit)
pi install git:github.com/user/repo@v1
pi install git:git@github.com:user/repo@v1.0.0

# Da directory locale
pi install ./path/to/local/package

# Gestione
pi remove npm:@acme/pi-tools    # Rimozione
pi list                          # Elenco pacchetti installati
pi update --all                  # Aggiorna Pi + tutti i pacchetti
pi update --extensions           # Aggiorna solo i pacchetti
pi update npm:@acme/pi-tools     # Aggiorna pacchetto singolo

Progetto locale vs globale

La differenza è importante:

pi install npm:@acme/tools         # Globale: ~/.pi/agent/settings.json
pi install npm:@acme/tools -l      # Locale: .pi/settings.json (condivisibile col team)

L’opzione -l scrive nel .pi/settings.json di progetto. Questo file può essere committato, così tutto il team ha le stesse dipendenze senza configurazione manuale.

Struttura di un pacchetto

{
  "name": "@acme/pi-tools",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"],
    "video": "https://example.com/demo.mp4"
  }
}

Anche senza il manifesto pi nel package.json, l’auto-scoperta funziona: se le directory extensions/, skills/, prompts/, themes/ esistono, vengono caricate automaticamente.

Filtrare le risorse

Se un pacchetto contiene molte risorse e vuoi caricarne solo alcune, puoi filtrare:

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:big-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

La sintassi è flessibile: [] significa nessuna risorsa di quel tipo, !pattern esclude match, +path include forzatamente, -path esclude forzatamente.

Pacchetti utili

Cerca su npm con keywords:pi-package:

• pi-share-hf — pubblica le sessioni OSS su Hugging Face
• pi-skills (badlogic) — web search, browser automation, API Google
• anthropics/skills — elaborazione documenti (docx, pdf, pptx, xlsx)

Uso temporaneo

Per provare un pacchetto senza installarlo permanentemente:

pi -e npm:@foo/bar                   # Extension temporanea
pi -e git:github.com/user/repo      # Da git

7. Strategia di integrazione: da zero a un ecosistema completo

Il bello di Pi è che non devi costruire tutto subito. Anzi, l’approccio migliore è esattamente il contrario: progressive enhancement. Parti dal minimo indispensabile e aggiungi complessità solo quando senti l’attrito.

Ecco un percorso di adozione graduale, pensato per accumulare valore senza affogare nella configurazione.

Livello 1 — Fondamenta (5-10 minuti)

Scrivi un buon AGENTS.md nel progetto. Non serve altro:

# Mio Progetto

## Stack
- Frontend: Next.js 15, TypeScript, Tailwind CSS
- Backend: Fastify, PostgreSQL, Prisma
- Testing: Vitest, Playwright

## Convenzioni
- [le tue regole qui]

## Comandi
- `npm run dev` — sviluppo
- `npm run test` — test
- `npm run lint -- --fix` — linting con auto-fix

Livello 2 — Ripetibilità (15-30 minuti)

Crea prompt templates per i task che esegui più spesso:

~/.pi/agent/prompts/
├── review.md        # Code review standard
├── refactor.md      # Refactoring con safety checks
├── test.md          # Generazione test automatici
├── commit.md        # Git commit message ben formattato
└── docs.md          # Generazione documentazione

Livello 3 — Competenze specializzate (30-60 minuti)

Aggiungi skills per domini verticali dove ti serve profondità:

~/.pi/agent/skills/
├── prisma-migration/    # Gestione migrazioni database
├── api-generator/       # Generazione endpoint REST
├── debug-checklist/     # Procedura di debugging sistematica
└── deployment/          # Workflow di deploy

Livello 4 — Automazione e protezione (1-2 ore)

Scrivi extensions che automatizzano e proteggono il workflow quotidiano:

~/.pi/agent/extensions/
├── gatekeeper.ts        # Blocca comandi pericolosi
├── git-auto-commit.ts   # Commit automatico a ogni turno
├── lint-on-write.ts     # Linting automatico dopo write/edit
└── context-monitor.ts   # Alert quando il contesto si riempie

Livello 5 — Ecosistema condiviso

Crea un Pi Package per il team:

{
  "name": "@acme/pi-tools",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"]
  }
}

Poi ogni membro del team lo installa localmente:

pi install npm:@acme/pi-tools -l

Il .pi/settings.json risultante può essere committato, così chiunque cloni il repository ha automaticamente le stesse personalizzazioni.

8. Best practices e workflow quotidiani

1. L’arte del system prompt a strati

Combina i diversi livelli di contesto per creare un sistema di istruzioni stratificato e coerente:

~/.pi/agent/APPEND_SYSTEM.md   ← Istruzioni personali globali
~/.pi/agent/AGENTS.md           ← Convenzioni globali (tutti i progetti)
../AGENTS.md                     ← Convenzioni monorepo / organizzazione
./AGENTS.md                      ← Convenzioni specifiche del progetto
./.pi/prompts/                  ← Template del progetto

Ogni strato aggiunge informazioni senza confliggere. Le istruzioni più specifiche (vicino al progetto) hanno la precedenza perché vengono concatenate dopo.

2. Hot Reload

Quando modifichi extensions, skills, prompt template o context file, non serve riavviare Pi. Usa:

/reload

Le modifiche vengono caricate immediatamente. I temi fanno addirittura hot-reload automatico, senza bisogno di comandi.

3. Gestione delle sessioni

Pi salva le sessioni come file JSONL con struttura ad albero. Questo ti permette di navigare la storia, creare fork e continuare da dove avevi lasciato:

pi -c                     # Continua l'ultima sessione
pi -r                     # Scegli tra le sessioni passate
pi --name "refactor-auth" # Nome descrittivo per la sessione
pi --no-session           # Sessione effimera (non salvata)
pi --fork <id>            # Crea un fork da una sessione esistente

Dentro Pi, i comandi interattivi per la gestione:

/tree      # Naviga l'albero della sessione
/fork      # Nuova sessione da un messaggio precedente
/clone     # Duplica il branch attuale
/compact   # Comprimi il contesto manualmente

4. Monitorare il contesto

Il contesto è una risorsa limitata. Puoi monitorarlo da un’extension:

pi.on("turn_end", (event, ctx) => {
  const usage = ctx.getContextUsage();
  if (usage && usage.tokens > 100_000) {
    ctx.ui.notify(
      "⚠️ Contesto quasi pieno! Considera /compact",
      "warning"
    );
  }
});

5. Scegliere la modalità giusta

Pi funziona in diverse modalità, ciascuna pensata per uno scenario specifico:

6. Trust model e sicurezza

Pi ha un modello di fiducia a due livelli per i progetti. All’avvio interattivo, chiede se fidarsi di un progetto che contiene risorse .pi/. Puoi gestire questo comportamento:

• Usa /trust per salvare la decisione in modo permanente
• In modalità non interattiva (-p, RPC), configura il comportamento predefinito:

{
  "defaultProjectTrust": "always"
}

I valori possibili sono "always", "ask" (default) e "never".

Da linea di comando:

pi --approve       # o -a: fidati automaticamente
pi --no-approve    # o -na: non fidarti mai

7. Il file settings.json

La configurazione di Pi vive in due file JSON:

• ~/.pi/agent/settings.json — configurazione globale
• .pi/settings.json — configurazione di progetto (committabile)

Qui puoi configurare tutto: modello, provider, skills directory aggiuntive, pacchetti, temi, modalità predefinite e molto altro.

9. Riepilogo e percorso di adozione

Abbiamo attraversato tutti i meccanismi di estensione di Pi. La cosa importante da ricordare non è la lista delle funzionalità, ma la filosofia che le unisce: adattare lo strumento al tuo modo di lavorare, non il contrario.

Ecco una visione d’insieme del percorso:

┌─────────────────────────────────────────────────────────┐
│                                                         │
│   GIORNO 1: AGENTS.md                                   │
│   ├─ Convenzioni, stack, comandi                        │
│   └─ Massimo impatto, minimo sforzo                     │
│                                                         │
│   SETTIMANA 1: Prompt Templates                         │
│   ├─ review, test, refactor, commit                     │
│   └─ I task ripetitivi diventano istantanei             │
│                                                         │
│   SETTIMANA 2: Skills                                   │
│   ├─ Domini specializzati (API, DB, deploy)             │
│   └─ Aumenta qualità e consistenza                      │
│                                                         │
│   MESE 1: Extensions                                    │
│   ├─ Gatekeeper, auto-commit, lint-on-write             │
│   └─ Sicurezza e automazione personalizzata             │
│                                                         │
│   MESE 2+: Pi Packages                                  │
│   ├─ Condividi le personalizzazioni col team            │
│   └─ Standard aziendale e coerenza tra progetti         │
│                                                         │
└─────────────────────────────────────────────────────────┘

Tabella comparativa dei meccanismi

Conclusione

Pi è stato costruito intorno a un’intuizione semplice ma potente: il coding agent migliore non è quello che fa più cose, ma quello che si lascia modellare meglio.

I quattro meccanismi che abbiamo esplorato — Context Files, Prompt Templates, Skills, Extensions — coprono l’intero spettro dell’estensibilità. Si parte da un file Markdown di dieci righe e si arriva a moduli TypeScript che intercettano eventi, registrano tool e trasformano l’agente in una piattaforma su misura.

Non serve costruire tutto. Non serve neanche costruire metà. Inizia con un buon AGENTS.md — ti cambia l’esperienza in dieci minuti. Poi, quando un task diventa ripetitivo, crea un template. Quando un dominio richiede profondità, scrivi una skill. Quando senti il bisogno di automatizzare o proteggere, passa alle extensions. E quando vuoi che il tuo team condivida le stesse personalizzazioni, impacchetta tutto.

La bellezza di questo approccio è che cresce con te. Non c’è un momento in cui “hai finito”. C’è un momento in cui lo strumento funziona esattamente come vuoi tu.

Fonti e riferimenti

• Documentazione ufficiale di Pi: pi.dev
• Repository GitHub: github.com/earendil-works/pi
• Standard Agent Skills: agentskills.io
• Anthropic Skills: github.com/anthropics/skills
• Pi Skills (badlogic): github.com/badlogic/pi-skills
• Approfondimento sui coding agent: nodeai.it

Articolo basato sulla documentazione ufficiale di Pi e sull’analisi dei sorgenti del progetto. Le osservazioni sullo stile di lavoro e le strategie di adozione graduale derivano dall’esperienza diretta con lo strumento.