Skills are new features: Building Skill-Centric Harness — Yogendra Miraje, FactSet

How do you keep an agent from rediscovering the execution path every time it performs a familiar task? For Yogendra Miraje, who introduces himself as a principal AI engineer at FactSet, that question sits inside financial data and research products. His earlier answer was a blueprint: a sequence of steps that tells the agent how to approach the work.

The opening example is a blueprint for NVIDIA earnings research and reporting. It breaks the work into a four-step recipe spanning retrieval, reasoning, and reporting. Looking back, Miraje recognizes the blueprint as an early, simple form of a skill: reusable instructions for completing a particular task.

The release of Agent Skills gave his team a shared format to adopt instead of maintaining its own blueprint standard. Anthropic launched Skills in October 2025; publication as an open standard followed in December. Miraje’s team moved from its internal recipes to skills and began building around them.

That changes the engineering question. In the audience, many people have written skills for Claude Code or Codex, but far fewer have added skill support to their own harnesses. The problem here is how to make skills work inside an agentic product—and how to keep that product coherent as its skill library grows.

In a conventional product, users navigate screens, buttons, forms, and dashboards. In an agentic product, they may speak directly to an agent, or an agent may make decisions behind the scenes that guide them through the product. Once the agent becomes the main interface, where does the behavior formerly attached to those controls live?

The useful separation is who, what, and how:

Skills provide a home for the business logic that shapes the agent’s behavior. In equity research and wealth management, workflows previously reached through buttons, menus, and screens can become skills. Skills become the product’s features.

That also changes who can contribute. Someone who understands the product can express how a workflow should run, without necessarily implementing a new screen. As more people in the company can author those features, engineers increasingly own the harness: the runtime that discovers, loads, and supports the skills.

A skill teaches an agent how to perform a specific task well. The model may already be able to attempt that task; the skill supplies the method it should follow. A simple package can be just Markdown. A more involved package can reference supporting files and executable scripts.

The heart of the package is SKILL.md, defined by the Agent Skills specification. Its front matter contains a name and description for discovery. Its body contains the instructions and business logic, including references to any supporting files or scripts. Keeping these responsibilities separate lets the harness advertise a capability without loading its full implementation into the conversation.

The minimum harness needs three components: a skill registry, a system prompt, and a file-read tool. If a skill runs scripts, it also needs an execution facility such as Bash or a code sandbox. Instruction-only skills do not require that additional execution layer.

A registry is a collection of names, descriptions, and paths. Miraje’s example has three capabilities:

The research step produces an intermediate document that either reporting skill can consume. The registry tells the agent what is available and where to read the instructions.

To expose those capabilities, concatenate each entry’s name, description, and path into the system prompt. Leave the skill bodies out. The agent first sees the catalog, selects a relevant skill, and then reads its file to obtain the instructions. This is progressive disclosure: discovery metadata is available up front, while task-specific instructions enter the context only when selected.

The agent loop keeps a messages array containing the conversation history. Each model call receives those messages and the available agent tools. A response requesting tools continues the loop; a response without a tool call becomes the final output. The essential sequence is:

1. Call the model with the current messages and tools.
2. If it requests tools, run them and append the tool interaction to the conversation.
3. Call the model again with the updated history.
4. When it returns without requesting tools, display its answer and stop.

Reading a skill is part of this same tool-driven interaction, so the loaded instructions become available to subsequent turns.

For a request to publish a report about NVIDIA, the agent first sees the available skill metadata. It activates company research, performs web searches, and produces Markdown. It then reads the reporting instructions and turns the research into HTML. The activation slide shows those two stages: company research followed by the build-report skill.

Miraje then displays an example report output. The important connection is the handoff: company research supplies the content, and the reporting skill supplies the presentation procedure. Both run through the same agent loop.

Why did the NVIDIA request produce HTML when the registry also contained a PDF skill? The PDF description restricted its use to requests that explicitly ask for a PDF report. The word PDF supplied a distinguishing trigger; the generic report request did not activate it. The description is part of the routing mechanism, not merely a label for a capability.

A compact SKILL.md example makes that boundary explicit:

---
name: report-pdf
description: Use only when the user explicitly asks for a PDF report.
---

# PDF report

Convert the Markdown report into a PDF document.

The description expresses when the user needs this skill. The body expresses what to do after selecting it. Describing only the implementation—such as saying that a skill converts documents—would leave more of the selection decision implicit.

Descriptions must also remain distinct and current. Overlapping descriptions make selection ambiguous; stale descriptions can prevent a skill from being triggered for the requests it should handle. This matters particularly in products for nontechnical users, where routing is mostly model-driven. Users should not have to memorize the skill catalog to obtain the right behavior.

Miraje initially organized his library around narrow data categories, including estimation analysis and fundamentals. Real requests did not follow those categories. They reflected work that users needed to complete, which forced repeated refactoring of the library. Starting with narrow use cases was useful; treating those initial boundaries as permanent was not.

The resulting shift is from data-oriented capabilities to recognizable workflows:

An earnings-preparation request may need estimates, but estimates are only part of the job. Naming and scoping the skill around preparation gives the agent a procedure aligned with the user’s goal. The same reasoning brings news and analyst ratings together under pre-market preparation.

After a model upgrade, Miraje’s agent began failing to obey its skills even though no lines in the skills had changed. On investigation, he found that the new model appeared to emphasize the beginning of a skill, while critical instructions sat at the end. This was a reported failure in his system; the talk does not identify the models or quantify the failures.

The operational consequence is straightforward: rerun evaluations whenever the model changes. A skill is a behavioral contract tied to a model, not documentation that can be assumed to retain the same effect across upgrades. Keeping the Markdown unchanged does not establish that the resulting behavior is unchanged. Evaluation has to test whether the new model still follows the procedure and its critical instructions.

For a small library, putting every skill’s metadata into the system prompt is a workable starting point. Miraje suggests considering shortlisting once the library exceeds roughly ten skills; this is a tentative design heuristic, not a measured routing limit. The next step is to select a relevant subset before constructing the prompt.

Two approaches can supply that shortlist:

• Embedding similarity search: retrieve skill entries that are similar to the user’s request.
• A smaller model: ask a separate model to select the entries that should be exposed to the main agent.

Both approaches move part of discovery ahead of the main agent call. The prompt now contains a selected catalog instead of the entire library.

With hundreds of skills, Miraje calls for hierarchy, metadata filters, and governance to keep the library searchable and coherent. At that scale, the problem extends beyond fitting descriptions into context. The system needs an organized way to find the right part of the library and maintain meaningful boundaries between its capabilities.

Miraje names five aspects of skill-library governance: admission, ownership, boundaries, lifecycle, and governance of the library as a whole. These need not become a bureaucratic bottleneck. Automated checks combined with human review can borrow practices already familiar from maintaining code.

Admission asks whether a proposed skill should exist independently or belong inside an existing skill. An automated registry gate, with a human review loop, serves a role analogous to pull-request review. It provides a point to examine the proposed addition before it becomes another capability the agent must distinguish and maintain.

Ownership answers who keeps the skill working. Application teams should maintain skills just as they maintain product features, with named maintainers analogous to code owners. Making authorship accessible to more people does not remove the need for someone to remain accountable for the resulting behavior.

Skills also need a lifecycle. Miraje recommends semantic versions, deprecation warnings when retiring skills, and changelog entries that record changes. Those practices make the evolution of a capability visible to the teams that depend on it.

The library needs maintenance beyond individual files. Periodic audits and skill-validation checks help preserve coherence as the number of skills grows. Just as a well-designed product has features that fit together, a useful skill library should remain understandable as a collection.

Finally, skills need explicit tool boundaries. Miraje recommends tool allowlists and access-controlled tools. A declared list and an enforced permission boundary are different: the current specification’s allowed-tools field is optional and experimental, and support varies by implementation. The harness and tool layer must enforce authorization; putting a tool name in a skill file does not establish access control.

Treating skills as features makes the harness a central engineering responsibility. It must support contributions from people who understand the product while preserving reliable execution. As the library grows, routing requires a different mechanism, not just further tuning of the original prompt. At enterprise scale, ownership, lifecycle controls, coherent discovery, and enforced boundaries become part of operating the product itself.