Equipping a dev team with AI: a shared skills catalogue

When every developer has their own prompts, the coding agent produces as many styles as there are people. A shared AI skills catalogue, versioned in the repository and governed by the tech lead, changes the game. Here is how to structure it, connect it to your information system without risk, measure it, and know when not to use the agent.

The problem: eight developers, eight ways of prompting

In most teams, coding agents were adopted from the bottom up: everyone found their own phrasings, tricks and personal context files. The result: the agent writes tests in three different styles, names migrations according to the mood of the day, and reviewers spend their reviews correcting form rather than checking substance. The know-how stays in conversation histories that nobody will ever reread.

The available studies call for caution. A controlled trial by METR, run in early 2025 with 16 experienced open-source developers, measured that they took 19% longer with AI tools, even though they thought they had saved time [1]. The 2025 DORA report describes AI as an amplifier of an organisation’s strengths and weaknesses, and lists among the capabilities that multiply its effect a clear, communicated stance on AI and access for AI to internal data [2][3]. A shared skills catalogue addresses precisely these two points.

This is what we tested in the iones lab experiment EXP-01 (EXP-01 report): 8 weeks, 8 developers and 1 lead from the BUILD team, on 2 client projects, with a versioned skills catalogue and 5 MCP servers.

What a skill is, and what it is not

The Agent Skills format

A skill is a folder that contains at least a SKILL.md file: a YAML header with a name and a description, then instructions in Markdown. The folder can bundle scripts, reference documents and file templates [4]. The format was designed by Anthropic, introduced in October 2025, then published as an open standard in December 2025 [5]; it is now supported by many tools, including Claude Code, Cursor, GitHub Copilot, Codex and Gemini CLI, according to the list kept on the standard’s website.

The key mechanism is progressive disclosure: at startup, the agent loads only the name and description of each skill (in the order of 100 tokens); it reads the full instructions only when the task matches, and the supporting files only if needed [4]. You can therefore maintain dozens of skills without saturating the context.

Skills, project rules, AGENTS.md: who does what

Sources: Claude Code documentation [6][7] and Cursor documentation [8][9]. AGENTS.md is an open format, now hosted by the Agentic AI Foundation under the Linux Foundation [10]; Cursor reads it, and Claude Code reads it when no CLAUDE.md is present [7].

Worth remembering: these files are context, not binding configuration. The Claude Code documentation says so explicitly and points to hooks and permission rules for blocking an action no matter what [7]. A skill guides; a prohibition is configured.

Anatomy of a skill: a complete example

An example for a Symfony project, versioned with the code:

.claude/skills/migration-doctrine/
├── SKILL.md
├── references/
│   └── conventions-bdd.md
└── scripts/
    └── verifier-migration.sh

---
name: migration-doctrine
description: Crée et vérifie une migration Doctrine selon les conventions du projet.
  À utiliser pour tout ajout ou modification de table, colonne, index ou contrainte.
---

## Étapes
1. Modifier l'entité, puis générer la migration avec `bin/console make:migration`.
2. Relire le SQL généré : une migration = un changement fonctionnel.
3. Toute colonne NOT NULL ajoutée à une table existante reçoit une valeur par défaut
   ou une migration de données séparée.
4. Nommer index et contraintes selon references/conventions-bdd.md.
5. Exécuter scripts/verifier-migration.sh (migration aller, retour, aller).

## Ne pas utiliser ce skill pour
- les changements de schéma touchant plus de trois tables : proposer un plan au lead ;
- les données de production : jamais d'exécution hors environnement local.

A few constraints of the standard to respect [4]: the name is at most 64 characters, in lower case, digits and hyphens, and must match the folder name; the description is at most 1,024 characters and must say what and when, and the SKILL.md stays under 500 lines, with the detail going into references/. The description is what triggers the skill: “help with the database” will never be chosen at the right moment.

Five useful families of skills

In EXP-01, the clearest gain came from the first two families: review comments on style and structure fell by 41%. The ticket-writing skill has an indirect effect: a well-written ticket is a better starting point, for a human as for the agent.

Connecting the information system: read-only MCP servers

A skill says how to do something; an MCP server gives access to information. In EXP-01, the team used 5 MCP servers: Redmine read-only, PostgreSQL read-only, Playwright, the project documentation and Git. An MCP server with write access to Redmine, on the other hand, was dropped after modifying 2 tickets by mistake. Since then, our rule is simple: read-only by default, write access only with justification and human validation.

Read-only access must be guaranteed at the source, not by an instruction. The MCP 2026-07-28 specification also states that tool annotations must be considered untrusted unless they come from trusted servers [11].

-- Rôle PostgreSQL dédié à l'agent, sur une copie anonymisée
CREATE ROLE agent_ro LOGIN PASSWORD '***';
GRANT CONNECT ON DATABASE projet_dev TO agent_ro;
GRANT USAGE ON SCHEMA public TO agent_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO agent_ro;
ALTER ROLE agent_ro SET default_transaction_read_only = on;

In Claude Code, a .mcp.json file at the root of the repository declares the servers shared by the team (“project” scope); the tool asks for approval before using these servers in an interactive session [12]. The same logic applies to API tokens: a read-only Redmine or GitLab token, specific to the agent, revocable. For recent changes to the protocol, see our article MCP: the 2026-07-28 specification.

Governance: a living catalogue, one owner

An ungoverned catalogue quickly turns back into a collection of individual prompts. In EXP-01, 6 skills were removed along the way: too generic, or contrary to the team’s conventions. Pruning is part of the job.

• One owner: the tech lead. They arbitrate, merge and remove.
• Everything goes through a pull request, like code: a modified skill is reviewed.
• A monthly review of 30 to 60 minutes with the team.
• No duplicates or contradictions: the Claude Code documentation warns that when rules contradict each other, the agent may pick one arbitrarily [7].

Monthly review checklist:

• [ ] Which skills were not triggered this month? To be removed or better described.
• [ ] Which review comments keep coming back? Candidates for a new skill.
• [ ] Did a skill produce a result contrary to the conventions? To be corrected or removed.
• [ ] Are the references (framework versions, commands) up to date?
• [ ] Does the “do not use for” section reflect the month’s incidents?

Measuring the impact

Measure before rolling out, on the same categories of tickets, then for at least eight weeks. The EXP-01 results:

Two indicators are enough to start: time per ticket, split between standard and complex tasks, and review comments per PR, sorted into form and substance. Add a qualitative signal: do the developers want to keep the tool? A senior developer on the BUILD team summed it up like this: “Before, the agent did what I asked. With the catalogue, it does what the team has decided.”

When not to use the agent

The most instructive figure in EXP-01 is perhaps the +9% time on complex tasks at the start. Balance only returned after we documented when not to use the agent. And we measured no gain on understanding the requirement, architecture or edge cases.

Our list, built into the catalogue:

• an ambiguous requirement or an incomplete ticket: clarify with the business first;
• an architecture decision or the choice of a structuring dependency;
• security code (authentication, permissions, cryptography): the agent can assist, but design stays human;
• business-logic edge cases that nobody has yet spelled out;
• anything that touches production.

For agents that act more autonomously, the rules get tougher: see our guardrails for autonomous AI agents.

Adoption cost and an eight-week plan

In EXP-01, adoption cost about 3 days of lead time and half a day per developer, or about 7 person-days for a team of 8, paid back in under a month.

Frequently asked questions

Moving from individual prompts to a team catalogue

A skills catalogue turns individual habits into team decisions: versioned, reviewed, measured. Start with repetitive tasks, keep the information system read-only, name an owner, measure before and after, and document from the outset when not to use the agent.

To frame this approach with your teams, discover our support in AI strategy and adoption. To reinforce a team that is already equipped, our dedicated developers work with these methods. A web agency? See also how to sell white-label AI offers. Or let’s talk about your team: reply within 48 to 72 hours.