How to turn your workflows into agent skills

There are a lot of agents now: Codex, Claude Code, OpenCode, Cursor, OpenClaw, autonomous agents, managed agents, and so on and so on.

For most business use cases, the harnesses feel similar. The magic is in how I teach the agent what to do. Enter skills. They are how you take a base agent and make it useful for your work.

What is an agent skill?

An agent skill is a folder that teaches an AI agent how to do a job. It is a set of instructions and supporting files.

Every skill has a required SKILL.md. That file tells the agent when to use the skill and what steps to follow. The folder can also include references, examples, templates, scripts, evals, and assets.

my-skill/
  SKILL.md
  references/
    examples.md
    gotchas.md
  templates/
    output.md
  scripts/
    helper.sh

The only hard requirement is SKILL.md.

Turn a job into a skill

Start with a real job the agent should do, for example:

• Writing a client update.
• Turning a call into next actions.
• Checking an invoice follow-up.
• Drafting a project risk note.
• Outlining a piece of content.

If you wanted to write a skill for client updates, start by decomposing how you already do it. The steps might look like this:

1. Get the client context.
2. Decide what kind of update this is.
3. Draft the message.
4. Review it for clarity, grammar, and tone.
5. Send or stage it in the tool where client updates go.

A lot of day-to-day work is compressed knowledge. Skill writing forces you to articulate the steps so an agent can do the work for you. Once you've identified the job, write the workflow down in a skill.

To turn a workflow into a skill, write down:

• The trigger: when this work starts.
• The inputs: what context the agent needs.
• The steps: what you do in order.
• The judgment calls: where quality depends on taste, policy, or risk.
• The stopping points: when the agent should ask before acting.
• The output: what done looks like.

The anatomy of a skill

Keep SKILL.md short. It is the entry point for the workflow. A minimal version looks like this:

---
name: my-skill
description: Use when the user wants [specific job, trigger phrases, common variants, and important exclusions].
---

# My Skill

One sentence: input -> workflow -> output.

## Use For

- [Specific job]
- [Specific variation]
- [Specific recurring pain]

## Workflow

1. Classify the request or mode.
2. Gather only the required context.
3. If this is [mode A], load references/mode-a.md.
4. If this is [mode B], load references/mode-b.md.
5. Load references/examples.md only when the output is taste-driven.
6. Load references/gotchas.md before risky or tool-specific work.
7. Follow the workflow steps.
8. Produce the expected result.
9. Stop for approval before external, expensive, or risky actions.

Skills use YAML frontmatter at the top of SKILL.md. Two fields are required:

• name: up to 64 characters, using lowercase letters, numbers, and hyphens.
• description: a clear summary of what the skill does and when the agent should use it.

The description is important because the agent uses it to find and invoke the skill.

A useful description looks like this:

Use when the user wants a client status update, project health update, blocker summary, delivery risk update, or stakeholder-ready progress narrative.

Anthropic's skill authoring best practices are useful for the exact technical rules.

Use examples, templates, and scripts

The core pattern is progressive disclosure. Keep SKILL.md concise, then point the agent to detailed files as needed.

References

References are for branch-specific context: API quirks, tool rules, escalation rules, voice guides, and gotchas. The main skill can point to the matching reference instead of carrying every branch inline.

client-update/
  SKILL.md
  references/
    status-update.md
    risk-update.md
    budget-update.md
    examples.md
    gotchas.md

Examples

Examples help when the output is taste-driven or fuzzy: emails, video scripts, content outlines, client updates, and tone examples.

Templates

Templates are for outputs that need the same shape: reports, pages, emails, or response structures.

Scripts

Scripts are for deterministic actions: folder creation, API calls, file setup, checks, and formatting. If the agent should do the same thing every time, make it a script instead of asking the model to improvise.

My rule of thumb: references and examples help the model think. Templates and scripts keep the output and mechanics steady.

Keep a gotchas file. When the agent makes a mistake, fix the output and add the lesson to the skill.

Useful gotchas can be simple:

• Ask before posting externally.
• Use confirmed owners, dates, payments, and project status.
• Use TBD for unknown facts.
• For US Eastern, use America/New_York.
• Treat weekly update as a reporting horizon by default.

Test it on real tasks

A skill is useful only if it works on real tasks. Test it with prompts that look like your work. A small test set is enough.

1. Save or invent 5-10 realistic prompts the skill should handle.
2. Define what a good result must include.
3. Run the skill against those prompts.
4. Review failures like workflow traces.
5. Patch the workflow, description, examples, or gotchas.
6. Run the same prompts again.

For an email skill, test prompts might look like:

• Write a warm follow-up to a client who missed a decision deadline.
• Draft a short update saying the timeline is at risk because we are missing assets.
• Turn this rough note into a polished, direct client email.

Checks might include:

• Does it ask before sending externally?
• Does it preserve the real facts?
• Does it use only confirmed dates and owners?
• Does it match the intended tone?
• Does it give the user a clear next action?

Anthropic's skill creator skill is super helpful and comes with built-in evaluations. I also have an autoresearch skill that I use to run improvement loops and make my skills better over time.

The habit matters more than the tooling. Keep prompts stable, run the skill against them, and compare behavior after every edit.

Skills require iteration over time. As you use them, you will find failure modes. Go back, update the workflow, and run the skill again. The payoff is that you can hand off more of your work to an agent and buy yourself more leverage and capacity.

Conclusion

Skills are how you give an agent the operating knowledge around your work: the steps, standards, examples, and tool rules that usually live in your head. If you want ready-made operational skills designed to keep experts high-output, install Pipa in the agent you already use.

Start at usepipa.com, or install the public skill pack directly:

npx skills add lunchpaillola/pipa-skills

You can inspect the public skill pack in the Pipa skills repo.