A skill-centric AI agent harness treats skills — not screens — as your product's feature set. Instead of shipping buttons, forms, and dashboards, your engineering team ships a harness that loads and runs agent skills on demand. Each skill is a self-contained instruction package that teaches the agent how to perform a specific task, and the harness is the runtime vehicle that governs how those skills are discovered, activated, and executed. This shift is already happening: Anthropic launched Agent Skills on October 16, 2025, published the format as an open standard at agentskills.io on December 18, 2025, and as of mid-2026 over 40 AI tools — including Claude Code, OpenAI Codex, Cursor, and Gemini CLI — support the format (Anthropic, agentskills.io).
The core insight: prompts define who the agent is, tools define what it can connect to, and skills define how a task gets done. Skills are where your business logic lives. Engineers build the harness; anyone with product knowledge can ship a skill.
Last verified: 2026-07-31 · Skills = the new features · Harness replaces the UI layer · Progressive disclosure is non-negotiable · Governance scales from 10 to 100+ skills · Skills are contracts versioned to a model, not documentation
Pricing/limits/model versions change often — re-check before relying on specifics.
What is a skill-centric AI agent harness?
A skill-centric harness is an agent runtime that organizes all product capabilities as skills — self-contained folders of instructions, scripts, and resources that the agent loads on demand — rather than hardcoding behavior into prompts or UI code. The harness provides a skill registry, a system prompt that advertises available skills, a file-read tool, and an agentic loop. Each skill contains a SKILL.md file with YAML frontmatter (name and description) and a markdown body with business-logic instructions (agentskills.io specification).
The "skill-centric" framing means the harness is a generic vehicle: it does not know what the skills do. It only knows how to discover them, present them to the model, load the right one at the right time, and provide tools for execution. Product teams — not just engineers — own the skills. For a real-world example of a skill in action, see our guide to building a portable AI skill file for video production.
Why skills are the new features in agentic products
What replaces the UI layer in an agent-first product?
In a traditional SaaS product, features lived in the UI: screens, buttons, dropdowns, forms. Users navigated the interface to reach functionality. In an agent-first product, the agent is the interface — the user either converses with it directly or the agent orchestrates behind the scenes. The question becomes: where do features live now?
The answer is a three-part separation of concerns:
| Layer | Question it answers | What it contains |
|---|---|---|
| System prompt | Who is the agent? | Role, persona, behavioral guidelines |
| Tools | What can it connect to? | APIs, databases, file systems, external services |
| Skills | How does a task get done? | Step-by-step instructions, decision logic, structured workflows |
Skills are the business logic layer. They are the new features. A wealth-management workflow that used to be a screen with 15 dropdowns is now a skill that instructs the agent on how to produce a portfolio analysis. An equity-research report that used to require navigating a dashboard is now a skill that directs the agent to gather data, structure findings, and produce a formatted report.
How does the engineer's role change?
The shift reframes engineering from shipping features to shipping harnesses. Engineers build the runtime infrastructure — the skill registry, routing mechanisms, tool execution sandbox, eval framework, and governance pipeline. Product domain experts (analysts, operations leads, subject-matter experts) write and maintain the skills. This is analogous to how a platform team builds the app framework while feature teams ship product code on top of it. This transition mirrors what we cover in our piece on how AI agents are reshaping enterprise IT workforces.
The harness must be a smooth vehicle for skills: it needs to discover skills cheaply, activate the right one at the right time, execute safely, and fail gracefully. Everything else is the skills' job.
What is the minimum viable skill support in a harness?
What are the three bare-minimum components for skills?
You need exactly three things to add skill support to any agent harness — no framework, no special library:
A skill registry — a collection of skills, each with a name, description, and filesystem path. This can be as simple as a JSON array or a directory listing.
A system prompt that advertises skills — concatenate each skill's name and description (not the full body) into the system prompt so the model knows what skills are available.
A file-read tool — so the agent can load a skill's
SKILL.mdbody when it decides to activate that skill. If your skills contain executable scripts, you also need a bash or code-sandbox tool.
That is the entire minimum viable implementation. The agentic loop — calling the model with the system prompt + tools, appending tool calls to the message history, and looping until the model produces a non-tool response — is the same loop you would build for any agent.
How does progressive disclosure work in a skill-centric harness?
Progressive disclosure is the core design principle that makes skills scale. Instead of loading all skill content into the context window at once, the agent loads information incrementally — only what it needs, only when it needs it (Anthropic engineering blog).
What are the three stages of progressive disclosure?
| Stage | What loads | Token cost | When |
|---|---|---|---|
| 1. Discovery | Name + description (frontmatter only) | ~100 tokens per skill | At startup, for all skills |
| 2. Activation | Full SKILL.md body |
< 5,000 tokens (recommended) | When the task matches a skill's description |
| 3. Execution | Referenced scripts, references, assets | As needed | Only when the instructions call for them |
A product with 50 skills might pay ~5,000 tokens just for the discovery stage (50 × ~100 tokens). But the full body of any single skill only loads when that skill is activated. An agent with 100 skills on hand has a small context footprint — the cost grows linearly with the number of skills at the discovery level, but activation and execution costs stay per-skill.
This is why skills scale better than stuffing everything into a system prompt. The spec recommends keeping SKILL.md under 500 lines and moving detailed reference material into separate files in a references/ directory (agentskills.io specification).
How do you write skill descriptions that route correctly?
Why are description fields called "routing signals"?
The description field in a skill's YAML frontmatter is the single most important factor in whether the agent picks the right skill. The model reads the description at the discovery stage and uses it to decide which skill to activate. If the description is vague, the skill will not be triggered. If two skills have similar descriptions, the agent will be confused.
Three rules for effective descriptions:
Align to the user's request language, not the skill's internal purpose. If the user asks for a "PDF report," the description should contain the word "PDF." A description like "Produces formatted document outputs" is about the skill; a description like "Use this skill only when the user asks for a PDF report" is about the user's request — and the latter is what routes correctly.
Keep descriptions distinct. If you have a "report HTML" skill and a "report PDF" skill, the descriptions must make the trigger condition unambiguous. Overlapping descriptions cause the model to either skip both or activate the wrong one.
Don't let skills go stale. If a skill's description no longer matches what the skill does, or if it references a workflow that has changed, the routing signal is broken. Stale descriptions are one of the most common reasons skills silently stop being triggered.
How do you structure skills by user intent instead of data model?
What happens if you cut skills by data model instead of use case?
A common mistake when building a skill library is to organize skills around the underlying data model or system capabilities — a skill for "fundamentals data," a skill for "estimates analysis," a skill for "analyst ratings." This feels natural to engineers because it mirrors the API or database structure.
But users do not think in data-model terms. They think in workflows: "I need a pre-market briefing," "I need earnings preparation," "I need a company report." When the skills are organized by data model, the agent has to chain multiple narrow skills together to serve a single user request — and each additional skill activation is a point where routing can fail.
The fix is to refactor skills to match user intent. Instead of separate skills for "estimates" and "fundamentals" and "analyst ratings," you build a single "pre-market briefing" skill that pulls from all three data sources. This reduces the number of skills the agent must navigate, makes each skill more self-contained, and aligns the routing signal with how users actually phrase requests.
Start narrow and refactor as real use cases arrive. It is normal to refactor the skill library multiple times as you discover how users actually interact with the agent.
How do you eval a skill-centric harness?
Why are skills contracts versioned to a model?
A skill is not documentation — it is an active contract between the harness and the model. The instructions in the SKILL.md body are parsed, interpreted, and followed by a specific model. When you upgrade the model — even to a newer version of the same model family — the way it reads, prioritizes, and follows instructions can change.
In production deployments, this has been observed directly: a model upgrade caused agents to stop obeying skills even though not a single line in any skill was changed. The root cause was that the new model paid more attention to the beginning of the skill body and less to the end — where critical instructions happened to live.
This means:
- Skills without evals are wishful thinking. You need a test suite that sends representative prompts to the agent and verifies that the correct skills are activated, the correct instructions are followed, and the output matches expectations. For a deep dive on this pattern, see our guide to building verification skills for multi-agent workflows.
- Re-run evals on every model upgrade. Treat skills as versioned artifacts. When the underlying model changes, the skill may need to be restructured (e.g., moving critical instructions from the end to the beginning).
- Track which model each skill was validated against. This is your version contract.
How does skill routing change as you scale past 10 skills?
What routing mechanism works at different skill library sizes?
The routing mechanism does not get tuned as you scale — it changes. What works for 5 skills breaks at 50 and is impossible at 500.
| Library size | Routing mechanism | How it works |
|---|---|---|
| 1–10 skills | Stuff all in system prompt | Concatenate name + description for all skills; the model picks from the full list |
| 10–100 skills | Similarity search / shortlisting | Use embedding-based similarity search or a smaller model to shortlist relevant skills, then inject only the shortlist into the system prompt |
| 100+ skills | Hierarchical skills + metadata filters + governance | Skills are organized into a hierarchy with metadata tags; the agent first navigates categories, then drills into specific skills; admission/ownership/lifecycle governance keeps the library coherent |
At 10+ skills, simply listing all descriptions in the system prompt starts to degrade routing accuracy — the model has too many options and descriptions start competing. At this point you need a pre-filtering layer: an embedding model that computes similarity between the user's request and each skill description, returning a ranked shortlist of 5–10 candidates that get injected into the system prompt.
At 100+ skills, even similarity search struggles — the descriptions overlap, the library becomes hard to search, and without governance it becomes incoherent. This is where hierarchy, metadata filters, and formal governance become non-negotiable. For more on this problem at a broader scale, see our guide on AI agent sprawl and governance.
What governance does a skill library need at enterprise scale?
What are the five aspects of skill library governance?
When the skill library reaches hundreds of skills across multiple teams, governance is the difference between a maintainable system and a swamp of broken, duplicated, abandoned skills. The framework borrows directly from established software engineering practices:
| Governance pillar | Core question | How to implement |
|---|---|---|
| Admission | Should this skill even exist? | Automated gate for the registry with human-in-the-loop review. Analogous to PR review: every new skill is evaluated to determine whether it belongs in the library or should be merged into an existing skill. |
| Ownership | Who maintains this skill? | Named maintainers for each skill — like CODEOWNERS in a repo. Skills without an owner rot. |
| Boundaries | What can this skill access? | Each skill has an allow-list of tools it may use. Tools are access-controlled per skill to enforce security boundaries. |
| Lifecycle | What happens to this skill over time? | Semantic versioning, deprecation warnings, changelogs. When a skill is removed, deprecation warnings give downstream users time to migrate. |
| Coherence | Does the library still make sense? | Periodic audits and validation checks to ensure the full library remains cohesive — no orphaned skills, no overlapping duplicates, descriptions still accurate. |
Governance does not have to be red tape. With proper automation and human-in-the-loop checkpoints, it can be lightweight. The key is borrowing practices that have worked in software engineering for decades: code review, ownership, versioning, access control, periodic refactoring.
What does a complete skill-centric architecture look like?
How do the pieces fit together end-to-end?
Here is the full pipeline from user request to skill output:
- User sends a request. The request enters the agentic loop.
- Harness assembles the system prompt. Skill name + description for all discoverable skills (or a shortlisted subset at scale) are injected into the system prompt. This is the discovery stage.
- Model evaluates the request against skill descriptions. The model identifies which skill(s) are relevant based on the routing signal in the descriptions. This is activation.
- Harness loads the relevant skill's
SKILL.mdbody. The file-read tool pulls the full instructions into context. - Model follows the skill instructions. It executes steps, calls tools, reads referenced files, and produces output. Scripts in the skill's
scripts/directory execute in the sandbox. - Loop continues until the model produces a final response. Tool calls and results are appended to the message history at each turn.
- Output is returned to the user.
At every stage, the harness enforces boundaries (tool allow-lists per skill), tracks state (message history), and provides the execution environment (sandbox, file system access, API connectivity). For a complementary perspective on multi-agent coordination patterns, see our guide on orchestrating AI agents like a company.
What this means for you
If you are a product or engineering leader: The shift from feature-shipping to harness-shipping is a real organizational change. Your engineers build the platform; domain experts build the skills. Invest in the harness (registry, routing, evals, governance) before you invest in a massive skill library — a good harness makes skills cheap to build and maintain.
If you are building an agentic product: Start with the three bare-minimum components (registry, system prompt, file-read tool). Ship a handful of skills. Refactor them by user intent as real usage data comes in. Add similarity search at ~10 skills. Add governance at ~100 skills.
If you are writing skills: Treat descriptions as routing signals — align them to user language. Keep SKILL.md under 500 lines. Move heavy content to references/. Write evals. Re-run them whenever the model changes. Version your skills.
FAQ
Q: What is a skill-centric AI agent harness?
A: A skill-centric harness is an agent runtime where all product capabilities are organized as skills — self-contained instruction packages the agent loads on demand — rather than hardcoded into prompts or UI code. The harness provides discovery, routing, and execution; the skills contain the business logic.
Q: What is the minimum needed to add skill support to an agent?
A: Three components: a skill registry (name, description, path for each skill), a system prompt that advertises skill metadata, and a file-read tool to load SKILL.md bodies on activation. If skills contain executable scripts, you also need a bash or sandbox tool.
Q: How does progressive disclosure work with agent skills?
A: Progressive disclosure loads skill content in three stages: discovery (name + description, ~100 tokens, at startup for all skills), activation (full SKILL.md body, <5000 tokens, when the task matches), and execution (referenced scripts/files, as needed). This keeps context lean even with dozens of skills registered.
Q: Why are skill descriptions called routing signals?
A: The model uses the description field to decide which skill to activate. Descriptions aligned to user request language (e.g., "use when the user asks for a PDF report") route better than descriptions about the skill's internal purpose (e.g., "produces formatted document outputs"). Vague or overlapping descriptions cause skills to be skipped or mis-activated.
Q: How many skills can you put in a system prompt before routing breaks?
A: Roughly 10 skills is the threshold where listing all descriptions in the system prompt starts to degrade routing accuracy. Beyond that, use embedding-based similarity search or a smaller model to shortlist 5–10 relevant skills per request. At 100+ skills, you need hierarchical organization, metadata filters, and formal governance.
Q: Why do skills need evals?
A: Skills are contracts versioned to a model. A model upgrade can change how the model interprets and prioritizes skill instructions — even with zero changes to the skill itself. Without evals, these failures are silent. Re-run evals on every model upgrade and track which model each skill was validated against.
Discussion
0 comments