Building Reusable AI Agent Skills

The first useful agent workflow is often written as a long prompt in one conversation. That is a fine experiment. It becomes an engineering problem when the workflow recurs: people paste the same context, new contributors discover rules by accident, output quality drifts, and a successful fix never reaches the next run.

An agent skill is a way to package that operating knowledge. It gives an agent a discoverable name, a specific job, a repeatable procedure, and the resources required to do the work. The value is not the folder alone. The value is converting a fragile, implicit ritual into a small product that can be reviewed, versioned, evaluated, and improved.

A Skill Is a Productized Workflow

OpenAI describes skills as reusable, shareable workflows: a name and description, workflow instructions, and supporting resources such as templates, examples, schemas, or tool access. Its skills guide (opens in new tab) makes an especially good design recommendation: small building blocks usually compose better than one huge end-to-end skill.

That makes skills different from both tools and agents:

A skill may call tools, but it should not disguise authority. The application still owns credentials, approvals, validation, and execution. A skill explains the procedure; it does not get to bypass the safeguards around the procedure.

Choose a Narrow, Observable Job

The best starting point is not “make our engineering agent better.” It is a repeated task with a clear entrance and a visible finish. For example: “turn a completed incident record into a draft postmortem that follows our template, cites evidence, and leaves ownership blanks when facts are unknown.”

Write the job contract before creating files:

Trigger: a user provides an incident record and asks for a postmortem draft.
 
Inputs: incident timeline, impacted services, evidence links, current template.
Output: a Markdown draft with summary, timeline, root cause, contributing factors,
actions, and explicit unknowns.
Never: invent timestamps, assign blame, publish externally, or create tickets.
Done when: every factual claim is traceable to supplied evidence or marked unknown.

That contract gives you criteria for scope decisions. “Search the incident channel” might be an approved tool step. “Message the on-call engineer” may require a separate, explicitly authorized action. “Write something useful even without evidence” is not a requirement—it is how confident fabrications enter a workflow.

Design the Skill Package

Use a predictable structure. The exact runtime format varies, but a small package can remain legible in any environment:

incident-postmortem/
├── SKILL.md             # trigger, procedure, constraints, completion checks
├── templates/
│   └── postmortem.md
├── references/
│   └── severity-policy.md
├── scripts/
│   └── validate-timeline.ts
└── evals/
    └── cases.md

SKILL.md is the entry point, not a dumping ground. Start it with a short description that makes selection reliable. Then state required inputs, the ordered workflow, output requirements, boundaries, and final checks. Put deep reference material in a named resource the agent can load only when relevant. This progressive disclosure keeps the active context focused and makes maintenance less painful.

---
name: incident-postmortem
description: Draft an evidence-based internal incident postmortem when an incident record is supplied.
---
 
# Required inputs
 
- Incident record and current postmortem template.
 
# Workflow
 
1. Extract only supplied facts into a timeline.
2. Run `scripts/validate-timeline.ts` before drafting.
3. Fill the template; mark missing evidence as `Unknown`.
4. Check every action has an owner and a measurable completion condition.
 
# Boundaries
 
- Never invent a cause, timestamp, owner, or customer impact.
- Never publish, message people, or create tickets.

Names and descriptions are product surface. A vague description such as “helps with operations” causes accidental activation; an overfitted description prevents a valid use. Include the object, the action, and the trigger condition.

Put Deterministic Work in Code

Language models are valuable for interpreting messy evidence, choosing a coherent outline, and drafting language. They are a poor replacement for a sort, a schema check, an ID lookup, or a permission test. Put deterministic work in scripts or tools and make the skill call them.

type TimelineEvent = { at: string; detail: string };
 
export function validateTimeline(events: TimelineEvent[]) {
  const invalid = events.filter((event) => Number.isNaN(Date.parse(event.at)));
  if (invalid.length > 0) {
    throw new Error("Timeline contains an invalid timestamp");
  }
 
  return [...events].sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
}

This division improves repeatability and reduces prompt complexity. Anthropic’s discussion of Agent Skills (opens in new tab) makes the same practical point: a skill may package instructions, resources, and code, while deterministic code handles work that token generation should not be asked to reproduce.

Keep code helpers narrow. A script should validate a timeline, render a template, or inspect a repository—not quietly become an unreviewed second agent. Document its inputs, output, and failure behaviour beside the skill so the agent knows when it is appropriate to run it.

Test Discovery, Execution, and Safety

A skill is not tested because its happy-path answer looks good once. It has at least three contracts to exercise:

1. Discovery: Does the name and description activate for the intended request and remain inactive for nearby, unrelated work?
2. Execution: Given complete inputs, does the agent follow the sequence, use the right resources, and produce the promised structure?
3. Safety: Given missing, contradictory, or adversarial inputs, does it mark uncertainty, avoid unauthorized actions, and preserve its boundaries?

Make a compact evaluation set from representative tasks and past failures:

Record the skill version, model/runtime, tools available, and result for important evaluation runs. A skill change can alter behaviour even when its wording looks like a harmless edit. Review it like an API change, run the cases before release, and add newly discovered failures to the suite.

Security is part of that review. Install skills only from trusted sources and inspect bundled instructions, scripts, dependencies, and network access before granting an agent access to them. A useful workflow package can also be a vehicle for unsafe instruction or code; provenance and least privilege are operational requirements, not bureaucracy.

Make Improvements Compound

After a run, capture only durable learning: a missing input, a recurring branch, a safe helper, a clearer exit condition, or an evaluation case. Do not keep appending every conversation transcript to the instructions. The skill should become sharper, not noisier.

The compound loop is simple:

Run → inspect outcome and trace → classify failure → fix the right layer
    → add an evaluation case → version the skill → run again

If the failure was a missing permission check, fix the tool boundary. If it was ambiguity in a routine, clarify the instruction. If it was a repeated formatting transformation, add a deterministic helper. If the task itself is now too broad, split the skill. This diagnosis prevents “add another paragraph to the system prompt” from becoming the only repair strategy.

Key Takeaways

• A reusable agent skill productizes a repeated workflow; it is not just a saved prompt.
• Start with a narrow, observable job and state trigger, inputs, output, authority, and failure conditions explicitly.
• Keep the entry instructions concise, put deep resources in named files, and package deterministic operations as small helpers.
• Test whether the skill is selected correctly, executes correctly, and behaves safely with incomplete or hostile input.
• Version and evaluate changes so successful fixes become durable capability rather than one-off conversational memory.

Next, we will look at agent tools themselves: how to give a model clear, narrow actions with schemas, validation, observability, and enough feedback to recover safely.