Skills Architecture

In the skills pattern, an agent loads specialized prompts and knowledge on-demand. Think of it as progressive disclosure for agent capabilities: rather than loading everything upfront, the agent only pulls in what it needs, when it needs it.

Where Skills Fit

While the skills architecture technically uses a single agent, it shares characteristics with multi-agent systems by enabling that agent to dynamically adopt specialized personas. This gives you similar benefits to multi-agent patterns (like distributed development and fine-grained context control) but through a lighter-weight, prompt-driven method rather than managing multiple agent instances.

flowchart TD
    U([User]) --> A[Single Agent]

    A -->|startup: loads names + descriptions only| SK[Skill Registry]

    SK --> S1[Skill: Code Review]
    SK --> S2[Skill: Data Analysis]
    SK --> S3[Skill: Creative Writing]
    SK --> S4[Skill: SQL Expert]

    A -->|skill triggered| LD["Load Full Skill Context\ninstructions + scripts + resources"]
    LD --> A

    A -->|discovers additional detail as needed| EX[Extra Files within Skill]
    EX --> A

    A --> R([Response])
            

Skills are packaged as directories containing instructions, scripts, and resources. Loading happens in three progressive levels:

This three-level structure keeps the agent's active context lean until specialization is actually needed.

Best For

• Single agents with many possible specializations that don't all need to be active at once.
• Situations where you don't need hard constraints between capabilities.
• Team distribution where different teams maintain different skills independently.
• Common use cases: coding agents, creative assistants, or general-purpose assistants with domain plugins.

As skills are loaded throughout a conversation, their context accumulates in the conversation history. This can lead to token bloat on subsequent calls: the more skills that get loaded in a session, the larger the context window grows, increasing cost and potentially degrading performance.

flowchart LR
    T1["Turn 1\nBase Agent"] -->|loads Skill A| T2["Turn 2\nBase + Skill A"]
    T2 -->|loads Skill B| T3["Turn 3\nBase + Skill A + Skill B"]
    T3 -->|loads Skill C| T4["Turn 4\nBase + Skill A + Skill B + Skill C"]

    T4 -->|token bloat risk| W[["Context window grows\nwith each skill loaded"]]
            

Skills are not limited to single-agent setups. In practice, the most sophisticated systems combine both: using multi-agent architecture for high-level orchestration and skills within individual agents for lightweight, on-demand specialization.

flowchart TD
    U([User]) --> SUP[Supervisor Agent]

    SUP --> A1[Research Agent]
    SUP --> A2[Engineering Agent]
    SUP --> A3[Writing Agent]

    A1 -->|loads on demand| SK1[Skill: Academic Papers]
    A1 -->|loads on demand| SK2[Skill: Web Scraping]

    A2 -->|loads on demand| SK3[Skill: React]
    A2 -->|loads on demand| SK4[Skill: FastAPI]
    A2 -->|loads on demand| SK5[Skill: SQL]

    A3 -->|loads on demand| SK6[Skill: Technical Docs]
    A3 -->|loads on demand| SK7[Skill: Marketing Copy]

    A1 & A2 & A3 -->|results| SUP
    SUP --> R([Response])
            

Where skills plug into multi-agent systems

• At the subagent level: each subagent stays lean by default and loads skills on-demand as the task requires. A research agent might load an "academic paper" skill or a "web scraping" skill depending on the source it needs to query.
• At the supervisor level: a supervisor can use skills to switch between orchestration strategies (for example, loading a "code review workflow" skill vs. a "report generation workflow" skill).
• As a substitute for lightweight subagents: if a specialization is prompt-driven and doesn't need its own tools or isolated reasoning loop, a skill loaded into an existing agent can do the job without the cost of spinning up a full subagent.

When to use a skill vs. a full subagent