Accueil / Articles

Pourquoi les compétences d’agent en chaîne échouent et la solution en trois niveaux qui fonctionne

Les chaînes de compétences complexes surchargent le contexte d’un agent. Construisez plutôt à l’aide d’atomes, de molécules et de composés, avec des exemples pour Claude Code, LangGraph, CrewAI et Agno.

Éditeur : REACTAPP.TOP9 min de lecture1996 mots

Sources: Why AI Agent Skills Break When We Chain Them and the Three-Layer Fix

Plus une chaîne de compétences d’agent comporte de niveaux, plus l’agent oublie. Un modèle de composition à trois niveaux permet aux compétences de rester fiables à n’importe quelle profondeur, et il est applicable à Claude Code, LangGraph, CrewAI et Agno.

Pourquoi les graphes de compétences plats échouent

En théorie, le graphe de compétences semble attrayant : on relie les compétences entre elles, on laisse l’agent parcourir le graphique et assembler les capacités selon les besoins. Une compétence en marketing appelle une compétence de recherche, qui à son tour appelle une compétence de scraping, ce qui crée un pipeline automatisé.

En pratique, cela échoue dans Claude Code, Codex, Cursor et tous les autres agents dont la fenêtre de contexte est limitée.

Voici le mécanisme. Au début, l’agent ne charge que les descriptions des compétences, ce qui suffit pour savoir ce qui existe. Le contenu complet d’une compétence est chargé lorsqu’elle est invoquée, puis il reste dans la session, consommant ainsi du contexte. Claude Code expose ouvertement ses limites : une fois une session compressée, une seule compétence ne peut conserver que 5 000 tokens au maximum, et toutes les compétences ensemble partagent 25 000 tokens. Cinq compétences complètes atteignent déjà ce plafond. En en chargeant dix, des éléments sont supprimés sans avertissement. D’autres agents rencontrent des obstacles similaires, mais avec des chiffres différents.

Les développeurs, quel que soit le framework utilisé, décrivent la même tendance. Une requête directe de B fonctionne de manière fiable. Une séquence A → B → C donne des résultats aléatoires. Une séquence A → B → C → D relève plus de l’espoir que de l’ingénierie. L’agent se retrouve avec trop d’instructions se disputant son attention et trop peu d’espace pour les stocker.

Les compétences de composition ne sont pas une idée fausse. Ce qui l’est, c’est de les représenter sous forme de graphique plat. Les exemples ici utilisent le format SKILL.md de Claude Code car sa documentation est la plus claire, mais le modèle des atomes, molécules et composés s’applique à tout agent disposant de compétences, d’outils ou de plugins.

Trois niveaux correspondant à une véritable composition

La plupart des frameworks d’agents organisent déjà les éléments en couches : outils directs, workflows en chaîne et délégation à des sous-agents. Claude Code rend cela explicite grâce à sa hiérarchie de commandes, de compétences et de tâches. Les trois niveaux présentés ci-dessous correspondent à Codex (compétences et commandes), Cursor (règles et outils) ainsi qu’à tout système permettant l’appel d’outils et l’exécution de sous-processus.

Atomes : une compétence, une tâche

Un atome correspond à un SKILL.md dédié à une tâche précise, présentant un comportement quasi-déterministe. Il n’appelle aucune autre compétence et ne prend aucune décision subjective. Il possède une entrée claire et une sortie claire.

---
name: verify-email
description: Verify an email address using Hunter.io API.
  Use when validating email deliverability before outreach.
allowed-tools: Bash
---
## Verify Email
1. Read the Hunter API key from $HUNTER_API_KEY
2. Call the Hunter email-verifier endpoint
3. Return: status (deliverable/risky/undeliverable), score, smtp_check
4. If the API errors, report the error. Do not guess.

Un test simple : si vous pouvez décrire toute une compétence en une phrase sans utiliser « et », il s’agit d’un atome. D’autres exemples incluent le traitement d’une URL en format Markdown, l’exécution d’un ensemble de tests, le contrôle de qualité d’un fichier, la récupération des différences d’une demande de fusion ou la recherche de records DNS.

Molécules : chaînes d’atomes décrites par écrit

Une molécule résout un problème plus complexe en exécutant de deux à dix atomes dans un ordre prédéfini. Ce qui la distingue d’un graphe de compétences, c’est que l’orchestration est écrite explicitement. La molécule ne dépend pas du modèle pour découvrir quels atomes existent ni pour deviner l’ordre à l’exécution.

---
name: qualify-lead
description: Research a company, find the right contact, verify
  their email, output a qualified lead card.
allowed-tools: Bash Read Write
---

## Qualify Lead
Execute these steps IN ORDER.
### Step 1: Company Research
Use /research-company. Capture: size, industry, funding, tech stack.
### Step 2: Find Contact
Use /find-contact. Target: VP Eng, CTO, Head of Platform.
### Step 3: Find & Verify Email
Use /find-email, then /verify-email.
If undeliverable, return to Step 2 (max 3 attempts).
### Step 4: Output Lead Card
Write structured markdown to leads/{company-slug}.md

Remarquez ce que le fichier évite de dire. Il ne demande jamais à l’agent de déterminer quelles compétences il lui faut. Il indique simplement la séquence : rechercher l’entreprise, trouver le contact, trouver l’adresse e-mail, puis la vérifier, dans cet ordre.

C’est cette précision qui assure la fiabilité. Une instruction vague comme « rechercher l’entreprise et trouver le meilleur moyen de la contacter » pousse le modèle à choisir des éléments au moment de l’exécution, et il peut parfois sauter une étape ou improviser un flux de travail qui ignore complètement ces éléments.

Composés : orchestration de sous-agents

Les composés interviennent lorsque une seule fenêtre de contexte ne suffit pas à contenir tout ce dont on a besoin. Ils utilisent l’outil Task de Claude Code pour lancer des sous-agents, chacun disposant de sa propre fenêtre de contexte et de ses propres compétences préchargées.

---
name: outbound-playbook
description: Run the full outbound playbook for a target segment.
  Spawns parallel agents to qualify leads and draft emails.
disable-model-invocation: true
allowed-tools: Bash Read Write Task Teammate
---

## Outbound Playbook
### Phase 1: Build Lead List
Ask the user for: target segment, company size range, geography.
Use /scrape-directory to pull matching companies.
### Phase 2: Parallel Lead Qualification (Task tool)
For each company (batch of 5):
- Spawn a subagent with qualify-lead preloaded
- Each subagent qualifies one company independently
### Phase 3: Draft Emails (Task tool)
For each qualified lead:
- Spawn a subagent with draft-email preloaded
### Phase 4: Human Review Checkpoint
STOP. Present sample drafts. Ask: "Review these. Adjust or proceed?"
Do NOT proceed without explicit user approval.
### Phase 5: Campaign Summary
Compile results to outbound/{segment}/campaign-summary.md

Deux caractéristiques distinguent les composés. Premièrement, les sous-agents disposent de fenêtres de contexte séparées, ce qui permet à l’évaluation des prospects de ne pas concurrencer l’élaboration d’e-mails pour l’espace disponible. C’est pourquoi les composés peuvent dépasser la limite qui entrave les chaînes complexes.

Deuxièmement, disable-model-invocation: true signifie qu’uniquement une personne peut lancer le playbook. Le modèle ne peut pas décider seul de démarrer une campagne externe. Les composés déclenchent des actions dans le monde réel, il est donc nécessaire qu’un humain contrôle cette action.

Structure des dossiers

.claude/skills/
  # ATOMS — single purpose, near-deterministic
  verify-email/SKILL.md
  find-email/SKILL.md
  find-contact/SKILL.md
  research-company/SKILL.md
  scrape-url/SKILL.md


# MOLECULES - explicit chains of atoms
  qualify-lead/SKILL.md
  review-and-test/SKILL.md
  draft-blog-post/SKILL.md
  # COMPOUNDS - subagent orchestration, human-driven
  outbound-playbook/SKILL.md
  feature-build-ship/SKILL.md

Les noms sont flexibles. C’est la séparation qui compte.

La même idée ailleurs

Rien ici n’est spécifique à SKILL.md. Chaque framework majeur d’agents dispose d’équivalents, et la syntaxe varie tandis que la logique de composition reste identique.

LangGraph : outils, chaînes, sous-graphes

Dans LangGraph, les atomes sont des fonctions décorées avec @tool ; les molécules sont des graphes séquentiels avec un ordre de nœuds explicite ; les composés, quant à eux, sont des sous-graphes ayant un état distinct.

from langgraph.graph import StateGraph
from langchain_core.tools import tool

# ATOM: a single tool
@tool
def verify_email(email: str) -> dict:
    """Verify email deliverability via Hunter.io."""
    response = requests.get(f"https://api.hunter.io/v2/email-verifier?email={email}")
    return response.json()

# MOLECULE: explicit sequential graph
workflow = StateGraph(LeadState)
workflow.add_node("research", research_company)
workflow.add_node("find_contact", find_contact)
workflow.add_node("verify", verify_email)
workflow.add_edge("research", "find_contact")
workflow.add_edge("find_contact", "verify")
graph = workflow.compile()

# COMPOUND: subgraph composition
parent = StateGraph(CampaignState)
parent.add_node("qualify", qualify_subgraph)   # each is a compiled graph
parent.add_node("draft", email_subgraph)       # with its own state
parent.add_node("review", human_review_node)

La différence avec Claude Code est qu’une molécule LangGraph est un graphe doté d’arêtes explicites plutôt qu’une liste d’instructions, de sorte que l’orchestration est structurale et non textuelle. Les conditions, les boucles et les branches parallèles s’intègrent plus naturellement de cette manière, bien que la configuration nécessite plus de code.

CrewAI : outils, tâches, équipes au sein des flux

CrewAI permet une représentation claire. Les atomes représentent les outils, les molécules sont des tâches liées entre elles par des dépendances context, et les composés correspondent aux équipes gérées par les flux.

from crewai import Agent, Task, Crew, Flow
from crewai.tools import tool


# ATOM: a tool
@tool
def verify_email(email: str) -> str:
    """Verify email deliverability."""
    return requests.get(f"https://api.hunter.io/v2/email-verifier?email={email}").text


# MOLECULE: tasks chained via context
researcher = Agent(role="Researcher", goal="Find company info", tools=[search_tool])
verifier = Agent(role="Verifier", goal="Verify contacts", tools=[verify_email])
research_task = Task(description="Research {company}", agent=researcher)
verify_task = Task(description="Verify the contact", agent=verifier, context=[research_task])
crew = Crew(agents=[researcher, verifier], tasks=[research_task, verify_task])


# COMPOUND: Crews inside a Flow
class OutboundFlow(Flow):
    @start()
    def qualify_leads(self):
        return qualify_crew.kickoff(inputs={"segment": self.state.segment})
    @listen(qualify_leads)
    def draft_emails(self, qualified):
        return email_crew.kickoff(inputs={"leads": qualified})
    @listen(draft_emails)
    def human_review(self, drafts):
        return drafts  # pause for human approval

Le paramètre context=[research_task] constitue le lien explicite. Ce paramètre indique à la tâche de vérification d’attendre la fin de la tâche de recherche avant d’agir, et de lire le résultat produit par cette dernière. S’il est omis, chaque tâche s’exécute indépendamment, ce qui fait disparaître la chaîne de traitement.

Agno : outils, agents, équipes

Agno propose la modélisation la plus simple. Les atomes correspondent à des fonctions @tool ; une molécule est un agent qui contient plusieurs outils ainsi qu’une description déterminant l’ordre d’exécution, tandis que les composés utilisent la structure Équipe.

from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools import tool


# ATOM
@tool
def verify_email(email: str) -> str:
    """Verify email deliverability via Hunter.io."""
    return requests.get(f"https://api.hunter.io/v2/email-verifier?email={email}").text


# MOLECULE: agent with ordered tools
qualify_agent = Agent(
    model=Claude(id="claude-sonnet-4-6"),
    description="Qualify a lead: research company, find contact, verify email. Execute in that order.",
    tools=[research_company, find_contact, find_email, verify_email],
)


# COMPOUND: team of agents
from agno.team import Team
outbound_team = Team(
    agents=[qualify_agent, email_drafter, campaign_reporter],
    description="Run the full outbound playbook for a target segment.",
)

Puisque l’ordre est défini dans la description, la molécule d’Agno ressemble davantage à l’approche SKILL.md que aux arêtes structurales de LangGraph. Elle est plus simple à écrire et un peu moins déterministe en ce qui concerne l’ordre.

Une architecture, de nombreuses syntaxes

Les détails d’implémentation diffèrent, mais la structure reste la même. Tout framework qui dépasse le stade de démos simplistes finit par présenter les mêmes trois couches, car les contraintes sont identiques partout : contexte fini, chaînage automatique peu fiable, et besoin de supervision humaine pour les tâches à haut risque.

Où cela échoue encore

  • Des atomes faibles gâchent tout ce qui se trouve au-dessus d’eux. Si un atome verify-email indique un succès alors que l’API a en réalité échoué, toute molécule ou composé qui en dépend génère des résultats erronés. Testez les atomes un par un avant de les combiner.
  • Les molécules comptant plus de dix atomes deviennent peu fiables. Dans Claude Code, le budget total après compactation constitue un plafond strict, et les autres agents ont eux aussi leurs propres limites. Limitez le nombre d’atomes des molécules à deux à dix et placez les étapes critiques en début de processus.
  • Les composés composés de huit à dix molécules atteignent eux aussi leur propre plafond. L’orchestrateur doit suivre quels sous-agents ont terminé leur travail, ce qu’ils ont produit et quelle étape suit, mais au-delà d’une certaine taille, il perd le fil. Divisez un composé plus gros en deux en ajoutant un point de contrôle manuel entre les deux parties.
  • L’invoquation automatique est moins fiable que l’invoquation explicite. Les évaluations des agents publiées par Vercel montrent que certaines compétences ne sont pas invoquées dans une grande partie des cas de test, et ce phénomène est probablement présent en dehors de Claude Code. Cela est acceptable pour les atomes. Pour les molécules et les composés, désactivez l’invoquation automatique et lancez-les manuellement.

Vous êtes le conducteur et l’agent est le moteur.

Pourquoi c’est important

La ressource rare n’est ni le calcul ni les tokens. C’est votre attention. Tapoter « vérifier cet e-mail » et tapoter « lancer une action externe pour le secteur fintech » exigent à peu près le même effort mental pour être lancés et suivis, pourtant les résultats diffèrent de plusieurs ordres de grandeur.

En bref, les atomes fournissent à l’agent des unités de travail prévisibles, les molécules enchaînent ces unités en séquences permettant d’accomplir des tâches, et les composés exécutent plusieurs séquences en parallèle dans des fenêtres de contexte distinctes. Chaque niveau augmente la quantité de résultats générés, tandis que votre propre attention reste globalement stable.

Cette architecture est déjà prise en charge, explicitement dans Claude Code ainsi que par des constructions équivalentes ailleurs. Le modèle de composition est ce que la plupart des développeurs n’ont pas encore mis en place.

La documentation des compétences de Claude Code se trouve à l’adresse code.claude.com/docs/en/skills, et le format SKILL.md suit la norme ouverte Agent Skills, compatible avec plusieurs outils d’IA. Les atomes, les molécules et les composés constituent un modèle proposé, et le code présenté est du pseudo-code destiné à expliquer ces concepts.