Vai al contenuto

Agenti e skill AI — configurazione condivisa

Questo documento descrive come il repository organizza agenti (subagent) e skill per Cursor e Claude Code, senza duplicare i file.

Problema che risolve

Cursor e Claude Code cercano configurazioni in cartelle diverse:

Tipo Cursor Claude Code
Subagent .cursor/agents/*.md .claude/agents/*.md
Skill .cursor/skills/*/SKILL.md .claude/skills/*/SKILL.md

Mantenere due copie degli stessi .md porta a drift: si aggiorna un file e l’altro tool resta indietro.

I file reali vivono solo sotto .claude/. Cursor accede agli stessi contenuti tramite link simbolici:

people-fe-v2/
├── .claude/
│   ├── agents/                    ← sorgente (file veri)
│   │   ├── component-dev.md
│   │   ├── page-dev.md
│   │   ├── service-dev.md
│   │   ├── lib-dev.md
│   │   └── style-dev.md
│   └── skills/                    ← sorgente (file veri)
│       ├── angular-developer/
│       └── angular-component-generator/
│
└── .cursor/
    ├── agents  →  ../.claude/agents    (symlink)
    ├── skills  →  ../.claude/skills    (symlink)
    ├── rules/                        ← solo Cursor (file veri)
    └── settings.json                 ← solo Cursor (file vero)

Modificare un agent o una skill in .claude/ aggiorna automaticamente ciò che vede Cursor in .cursor/agents e .cursor/skills.

Cosa resta specifico per tool

Path Tool Note
.claude/agents/, .claude/skills/ Claude Code, Cursor (via symlink) Unica sorgente da editare
.cursor/rules/*.mdc Cursor Regole progetto (formato .mdc)
.cursor/settings.json Cursor Plugin, preferenze IDE
CLAUDE.md Claude Code (orchestrazione), contesto generale Non duplicare qui il contenuto degli agent

Agenti disponibili

Agente Scope
component-dev src/components/**
page-dev src/pages/**
service-dev src/services/, src/models/, src/guards/, src/interceptors/, src/utils/
lib-dev src/lib/** (Design System — solo dopo decisione esplicita)
style-dev src/styles/, SCSS dei componenti

In Cursor vengono usati come subagent (delega via Task). In Claude Code come agenti definiti in .claude/agents/.

Skill disponibili

Skill Path Uso
angular-developer .claude/skills/angular-developer/ Linee guida ufficiali Google (signals, forms, routing, ARIA, test, …) e cartella references/
angular-review .claude/skills/angular-review/ Code review del diff vs develop secondo le rules in .claude/rules/
people-feature-docs .claude/skills/people-feature-docs/ Scrive o aggiorna documentazione MkDocs per una funzionalità (input: feature + contesto nuova/esistente)

Workflow per il team

Aggiungere o modificare un agent

  1. Crea o modifica solo .claude/agents/nome-agent.md (frontmatter YAML + istruzioni in markdown).
  2. Non creare copie sotto .cursor/agents/ — è un symlink.
  3. Committa il file in .claude/agents/.

Aggiungere o modificare una skill

  1. Crea la cartella .claude/skills/nome-skill/ con SKILL.md (frontmatter name e description obbligatori).
  2. Eventuali references/, script o asset restano nella stessa cartella skill.
  3. Non duplicare sotto .cursor/skills/.

Dalla root del repository:

./scripts/align-cursor-claude.sh

Equivalente manuale:

rm -rf .cursor/agents .cursor/skills
ln -s ../.claude/agents .cursor/agents
ln -s ../.claude/skills .cursor/skills

Verifica:

ls -la .cursor/
# agents -> ../.claude/agents
# skills -> ../.claude/skills

graphify — knowledge graph condiviso

Oltre ad agent e skill, il progetto usa graphify (CLI installato globalmente, non una dipendenza npm) per interrogare un knowledge graph del codebase invece di grep/lettura file estensiva. Anche qui, due configurazioni specifiche per tool che non vanno duplicate a mano:

Path Tool Note
.cursor/rules/graphify.mdc Cursor Regola alwaysApply: true, generata con graphify cursor install. Rigenerarla con lo stesso comando se persa.
Sezione "## graphify" in CLAUDE.md + .claude/hooks/graph-staleness.sh Claude Code Scritti a mano (non tramite graphify claude install, che scriverebbe anche un hook PreToolUse non presente).

Il grafo (graphify-out/graph.json + graph.html + GRAPH_REPORT.md) non è versionato (/graphify-out in .gitignore) e va generato localmente:

graphify extract . --code-only   # build iniziale, AST-only, nessuna chiave LLM richiesta
graphify update .                # dopo edit su src/**, mantiene il grafo aggiornato

Hook Git (post-commit, post-checkout) installati via graphify hook install lo aggiornano automaticamente. Sintassi completa: graphify --help.

Git e piattaforme

  • I symlink sono tracciati da Git come link, non come copie del contenuto.
  • macOS / Linux: funzionamento standard.
  • Windows: può servire git config core.symlinks true e privilegi per creare symlink; in caso di problemi usare WSL o ricreare i link con mklink /D (cmd come amministratore).

Riferimenti nel progetto