Skills define how an agent completes a task, while prompts define its identity and tools define its connections.
2
A harness can support skills with a registry, a system prompt, and a basic file-read tool.
3
Large skill libraries need search, ownership, versioning, audits, and human review to remain usable.
Summary
Yogendra Miraje describes how FactSet moved from its own blueprint format to open-source skills and began treating skills as the feature layer of agentic products. A skill contains instructions for completing a task, with skill.md holding its name, description, business logic, references, and scripts. The harness needs a registry, a system prompt, and file access, while progressive disclosure keeps full skill bodies out of the initial context. Miraje explains that descriptions act as routing signals, so words such as "PDF" or "HTML" can determine which skill runs. He is also clear about the operational limits. Skills can stop being followed after a model upgrade, even when the skill itself has not changed, so they need evals. Once a library grows beyond roughly ten skills, it needs retrieval. At hundreds of skills, it needs governance for admission, ownership, boundaries, lifecycle, and coherence.
Skills move business logic into the agent interface
Miraje says traditional products exposed features through screens, buttons, forms, and dashboards. In agentic products, the agent may be the main interface, which raises the question of where features belong. Prompts define who the agent is, tools define what it can connect to, and skills define how a task gets done. Skills hold the business logic that shapes the agent's behavior. Workflows such as equity research and wealth management used to appear as interface elements, but can now be represented as skills. Miraje also says people with a strong understanding of the product can ship these skills, while engineers increasingly build the harness in which the skills run.
Miraje defines an agent skill as "a standardized way to teach AI agents how to do a specific task well." A simple skill may contain only Markdown, while a complex one can reference other files and executable scripts. The skill.md file is its center. The front matter contains the name and description used for discovery, while the body contains business logic and instructions. References to files and scripts can also sit in the body. The model can work without a skill, Miraje says, but should perform better when the relevant instructions are available.
A minimal harness needs a registry, prompt, and file access
The smallest harness that supports skills has three parts: a skill registry, a system prompt, and a basic file-read tool. If skills run scripts, the harness also needs Bash or a code-running sandbox. The registry is a collection of skill names, descriptions, and paths. Miraje's example includes a company research skill that searches the web and produces Markdown, plus report HTML and report PDF skills that convert the Markdown into different formats. The harness concatenates the registry metadata into the system prompt, then runs the normal agent loop with messages and tools.
Progressive disclosure keeps full instructions out of the first context
The registry places each skill's name, description, and path in the system prompt, but it does not place the complete skill body there. The agent first sees the available skills, chooses one, and then reads and follows that skill's instructions. Miraje calls this progressive disclosure. In his example, a request to publish a report about NVIDIA activates the company research skill for web searches, followed by a report-building skill. The agent loop keeps tool calls in the message history and stops when the model returns no further tool call.
Skill descriptions route requests through distinct trigger words
Miraje calls descriptions "routing signals." His report HTML and report PDF skills are separated by the user's requested output. The PDF description says to use the skill only when the user asks for a PDF report, so the word "PDF" triggers that route. Descriptions should match the user's request rather than describe the skill in general. They also need to be distinct, since overlapping descriptions can cause the wrong skill to run or prevent a skill from running. Miraje says product skills are often model-driven, so nontechnical users do not need to remember a list of skill names.
Skill libraries should follow user intent as it becomes clearer
Miraje learned to organize skills around user intent rather than the underlying data model. His first library used narrow categories such as estimation analysis, fundamentals, news, and analyst ratings. Real requests did not follow those data-model boundaries, so he repeatedly refactored the library. He gives earning preparation as a better name than estimation analysis, and pre-market briefing as a better name than a news and analyst rating skill. Starting with narrow use cases is acceptable, but the library should change as the team discovers how people actually use the product.
Evals are contracts that catch model-specific skill failures
After FactSet updated its model, the agent began failing to obey existing skills even though no skill instruction had changed. Miraje found that the new model focused on the beginning of the skill while important instructions were at the end. That experience led him to argue that skills without evals are "really just wishful thinking." Skills are not merely documentation. He describes them as contracts versioned to a model, which means every model upgrade should trigger another evaluation run. A skill can therefore regress because of a model change, even when its text remains identical.
Large skill libraries need retrieval and governance
Putting every skill into the system prompt works only while the collection is small. Miraje suggests treating more than ten skills as a point to start shortlisting them with embeddings and similarity search, or with a smaller model that selects candidates. At hundreds of skills, the library needs a hierarchy, metadata filters, and governance to remain searchable and coherent. He names five governance areas: admission, ownership, boundaries, lifecycle, and coherence. Admission asks whether a new skill should exist at all. Ownership assigns maintainers. Lifecycle includes semantic versions, deprecation warnings, and changelogs. Periodic audits and validation checks help keep the collection coherent, while tool allow lists enforce boundaries.
"Prompts define who the agent is. Tools define what it can connect to. And skills really tell you how a task gets done."03:37
Who should watch
You are building an agentic product where the agent is becoming the main interface and need a place for product-specific business logic.
Your harness supports tools or prompts but has no clear registry or loading pattern for reusable skills.
Your skill library is growing, model upgrades cause regressions, or teams are adding overlapping skills without ownership and review.
