Anyone who has shipped a multi-capability agent knows the pattern. You start clean. Then the product needs more. You append instructions. Then edge cases. Then domain-specific rules for each capability. Six months later your system prompt is 3,000 tokens of competing guidance that the model has to reconcile on every single call — whether it needs that context or not.
The problem isn't prompt engineering skill. It's architecture. You're treating instruction delivery like a static config file when it should be dynamic.
This is the same problem software engineering solved decades ago with modular design. You don't load every library into memory at startup. You import what you need, when you need it.
Skills bring that principle to agent instruction design.
What Skills Are
Skills are self-contained instruction packages that an agent loads on demand. The agent's context stays lean — only skill names and descriptions are present at startup. When the agent determines it needs a specific capability, it fetches the full instructions at that moment and executes within them.
Three properties make this meaningful at scale:
Isolation — each skill's instructions are scoped. They can't conflict with each other because they're never in context at the same time unless explicitly needed.
Token efficiency — you pay only for what's active. An agent with ten skills doesn't carry ten sets of instructions into every call.
Maintainability — skills are versioned and updated independently. Changing how your agent handles one domain doesn't touch anything else.
This is progressive disclosure applied to LLM context management.
Strands and the AgentSkills Plugin
Strands is AWS's open-source agent SDK for Python and TypeScript. It takes a model-driven approach — instead of hardcoding orchestration logic, the LLM itself decides when to call tools, which order to execute steps, and when it has enough information to respond. This makes agents significantly more flexible without requiring complex orchestration code.
Strands ships with built-in tool support, multi-agent orchestration, and a plugin system for extending agent behavior. One of those plugins is AgentSkills — a production implementation of the progressive disclosure pattern.
Setting up an agent with Strands takes less than ten lines:
from strands import Agent
agent = Agent(system_prompt="You are a helpful assistant.")
response = agent("What is the capital of France?")
Adding skills is one extra step:
from strands import Agent, AgentSkills
plugin = AgentSkills(skills="./skills/")
agent = Agent(plugins=[plugin])
From that point, the agent manages skill discovery and activation automatically — you don't wire any routing logic.
How AgentSkills Works in Detail
The plugin operates in three phases:
- Discovery At initialization, AgentSkills scans your skills directory and injects only the skill names and descriptions into the system prompt:
<available_skills>
<skill>
<name>email-drafter</name>
<description>Drafts professional emails from a plain-English brief.</description>
</skill>
<skill>
<name>bug-investigator</name>
<description>Analyzes errors and returns a structured diagnosis.</description>
</skill>
<skill>
<name>git-commit-writer</name>
<description>Writes conventional commit messages from a change description.</description>
</skill>
</available_skills>
That's all the agent sees upfront — names and descriptions. No instructions, no domain logic, no token cost beyond the metadata.
2. Activation
When the agent receives a message it determines requires a specific skill, it calls the built-in skills tool with the skill name as the argument. This is a standard tool call — the same mechanism the agent uses for any other tool. No special routing, no conditional logic on your side.
3. Execution
The tool returns the full contents of the SKILL.md — instructions, rules, output format, everything. The agent now operates within those instructions for that response. Activated skills persist in agent state for the remainder of the session, so they don't need to be re-fetched on follow-up messages in the same domain.
Defining a Skill
A skill is a directory with a single SKILL.md file. The file has two parts: a YAML frontmatter header that the plugin reads, and a markdown body that becomes the agent's instructions.
skills/
└── bug-investigator/
└── SKILL.md
---
name: bug-investigator
description: "Analyzes an error message or stack trace and returns a structured diagnosis with root cause and fix."
---
# Bug Investigator Skill
You are a senior software debugger. When given an error message or stack trace, respond in this exact format:
🔍 Root Cause:
<one clear sentence explaining why this error occurs>
🛠 Fix:
<step-by-step instructions to resolve it>
✅ Example:
<a minimal corrected code snippet>
Rules:
- Be precise — if the error is ambiguous, ask one clarifying question.
- Always explain the why, not just the what.
- Keep the example under 10 lines.
The name field must be lowercase alphanumeric with hyphens, 1–64 characters. The description is what the agent reads to decide whether to activate the skill — write it as a clear, specific one-liner. Vague descriptions lead to wrong activations.
An optional allowed-tools field restricts which tools the skill can use:
---
name: pdf-processor
description: Extracts text and tables from PDF files using shell scripts.
allowed-tools: file_read shell
---
Two Ways to Define Skills
Filesystem-based is the standard approach — each skill in its own directory, versioned alongside your code, easy to review and update independently.
Programmatic is useful when instructions need to be generated at runtime — pulled from a database, built from environment config, or constructed dynamically per tenant:
from strands import Skill, AgentSkills, Agent
skill = Skill(
name="summarizer",
description="Condenses any text into a bullet-point summary preserving all key facts.",
instructions=(
"Extract the 3-5 most important points as bullet points. "
"Add a one-sentence TL;DR at the top. "
"Do not add information not present in the source text."
)
)
plugin = AgentSkills(skills=[skill])
agent = Agent(plugins=[plugin])
Both approaches compose cleanly:
plugin = AgentSkills(skills=["./skills/", dynamic_skill])
This is the practical setup for most production agents — static skills for stable capabilities, programmatic skills for anything that varies by environment or user context.
When to Reach for Skills
Skills aren't the right tool for every agent. If your agent has one job, a well-crafted system prompt is simpler and sufficient.
Skills pay off when:
- Your agent handles genuinely different domains where instruction sets would conflict
- You're optimizing for token cost at scale across high-volume calls
- You need independent versioning of capabilities across a team
- You're building toward a multi-skill agent that will grow over time They're a step below full multi-agent orchestration — more structure than a monolithic prompt, less overhead than spawning separate agents per capability.
Try It
Full project with Streamlit UI on GitHub:
👉 https://github.com/miladrezaei-ai/strands-agent-skills
git clone https://github.com/miladrezaei-ai/strands-agent-skills
cd strands-agent-skills
uv sync
aws configure # or AWS SSO
uv run streamlit run app.py
Where does your current agent prompt need this kind of separation? Would love to hear what you're building.