Agent Skill Files: Package a Procedure a Harness Can Version

An agent skill file is a short, versioned document that describes one repeatable procedure: when it applies, the steps to follow, the tools it may use, the points where a person must approve, and how to tell the work is done. A harness loads the file when a task matches it, which keeps the procedure outside the model and lets a team review, update or retire it without retraining anything or rewriting one long prompt. Done well, a skill file turns know-how that lives in someone's head into something an operations leader can read, challenge and assign.

Key takeaways

• A skill file covers one procedure, not a company's entire knowledge base.
• Keep each file in the harness under version control, with a named owner who approves changes.
• Every file should state its trigger, ordered steps, tool scope, approval points and a done check a reviewer can inspect.
• Test each new version against recorded past cases before it touches live work, and keep the previous version ready to restore.
• Retire a skill when the procedure changes or the file adds more risk than value, without editing unrelated skills.

What belongs in a skill file

A skill file is narrower than a company handbook. It describes one procedure that recurs, such as preparing a revised quote, following up on a late delivery or drafting a supplier reminder. Most useful files share the same fields, which makes them easy to review side by side:

• Name and purpose, written as a sentence a manager would recognize
• Trigger conditions, stating which requests the skill handles and which it must route elsewhere
• Required inputs and the sources the agent may read
• Ordered steps, short enough to follow without interpretation
• Tools in scope, with the specific actions each tool may perform
• Approval points, where the agent stops and waits for a named person
• Done check, the evidence a reviewer can verify
• Owner and version history, including the reason for the last approved change

The trigger and the done check matter most. Without a trigger, the harness loads the file for requests it was never meant to handle. Without a done check, nobody can tell whether a finished task was actually finished.

Why the procedure should live outside the model

A procedure buried in a long system prompt is hard to change safely. Someone copies a paragraph into another prompt, edits one line for a new case and forgets the original. When the underlying model changes, the team has to retest everything that was mixed into the same text. A harness solves this by deciding, for each task, which context, tools and permissions the model receives. A skill file is the unit the harness loads, so the procedure can change on its own schedule.

Tools follow the same logic. The Model Context Protocol provides a standard way to connect models to external tools and data, so a skill file can name the tool and the allowed action rather than carrying credentials or custom integration logic. For a broader view of the layer that does this work, see What is an AI harness? A practical business guide. For the reusable-procedure pattern itself, AI Agent Skills: Reusable Procedures Instead of Long Prompts explains why short procedures outperform a single growing prompt.

Step by step: write your first skill file

Choose a procedure that already runs the same way most of the time and has a visible finish. Leave out anything where the right answer depends on judgment that nobody has written down yet. Then follow this sequence:

• Step one: ask the person who does the work to walk through one recent case, then write the steps in the order they actually happen, including checks they only skip when the case is simple.
• Step two: mark every point where money, customer data, external messages or scheduled commitments change, and assign an approver to each one.
• Step three: list the tools the skill may call, then remove any action the procedure does not need. Keep read access separate from write access.
• Step four: write the done check as things a reviewer can confirm, such as a required field being filled, a figure matching its source or a message leaving through the approved channel.
• Step five: collect five to ten past cases with known good outcomes, and record what the correct result looked like for each.
• Step six: run the draft skill against those cases in a test environment, review every difference, and only then mark version one as approved for live work.

The last step is where most first drafts change. Reviewers usually find a missing exception, a tool that is broader than necessary or a done check that depends on something the agent cannot see.

Illustrative scenario: a quote revision skill

Illustrative scenario: a catering company wants an agent to revise an event quote when the guest count changes. The skill's trigger is a written change request that includes a new headcount. It may read the price sheet and the event record, and it may draft a revised quote, but it cannot send anything. The approval point requires the sales lead to confirm the draft before it leaves the company. The done check asks that every revised line match the price sheet and that the change appear in the event record. If the headcount is missing or contradicts the event record, the skill tells the agent to ask a question instead of guessing.

Notice what the file does not contain. It does not hold the company's full pricing policy, its contract templates or its scheduling rules. Those belong to other skills or to reference sources the skill points to, which means any one of them can be updated without rewriting the quote procedure.

Version, test and roll out each change

Treat a skill file like a small piece of software. Each change receives a new version number, a short note on what changed and why, and an approval from the owner. Run the new version against the recorded cases and compare its results with the current version, paying attention to the cases where the two disagree. Anthropic's engineering guidance on evaluating agents describes the same practice: fixed tasks, graded outcomes and repeated runs, so that changes are judged on evidence rather than impressions. Keep the previous version loaded or instantly available, so that a failure in live work can be reversed by changing one reference in the harness. AI Agent Definition of Done: Demand Evidence covers how to require that evidence before a result is accepted.

When to retire a skill

Retirement is as important as creation, and it is the step most teams skip. A skill file that no longer matches the business keeps being loaded, and the agent keeps following instructions that nobody intended anymore. Retire a skill when one of these conditions applies:

• The business procedure has changed and the file still describes the old version.
• A tool or permission the skill depends on has been withdrawn or narrowed.
• Recent evaluations show the skill no longer meets its done check.
• A newer skill covers the same procedure, and two files now compete for the same trigger.
• No named owner can explain what the skill is for.

To retire a file, remove it from the harness load list, archive its version history with the reason, and confirm that no other skill referenced it. Retiring one file should never require editing several others. If it does, the skills are too tightly coupled, and that coupling deserves its own review. The tool scope for each file is easier to audit when it is written down, as in AI Agent Tool Permissions Matrix: A Least-Privilege Template.

How Be Human handles skill files under management

Be Human treats skill files as part of the operating context that stays under the company's control. A first engagement defines the useful role, the procedures it needs, the tools and permissions each skill may use, the approval boundaries and an observable success criterion for each one. During managed operations, the team monitors how skills run, schedules recurring evaluations, reviews permissions, maintains the integrations the skills depend on and handles incidents through a documented response path. Changes to skill files are proposed, tested against recorded cases and approved by the company's owner before they reach live work, and retired files are archived with their reasons. If you are not sure which procedure to start with, the free Be Human AI diagnostic can help you find the first task worth handing to an agent.

Frequently asked questions

Is an agent skill file the same as a system prompt? No. A system prompt sets the agent's general role, tone and standing rules, while a skill file holds one procedure with its trigger, steps, tool scope, approval points and done check. A harness can load a skill only when a matching task appears, which keeps the agent's standing context shorter. Both should be reviewed, but they change for different reasons and should not be merged.

Do I need a specific platform to use skill files? Not necessarily. The format is a document, so the real requirement is a harness that can load the file for matching tasks, record which version ran and enforce the tool scope the file declares. Whether you build that layer yourself or use an existing product is a separate decision, and it depends on how much of the operating work your team wants to own.

How many skill files should a company start with? Start with one, and two at most. Choose a procedure that recurs, has a clear finish and produces a visible result when it goes wrong. Adding several files before the first one has been tested against real cases makes it difficult to tell which file caused a problem.

Who should own a skill file? A named person from the team that performs the procedure should own it, not the technical team alone. The owner approves changes, explains the intent behind each step and decides when the file should be retired. The technical side maintains the tools, credentials and permissions that the file references.

Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.