Agent skills tend to fail the same way. They work in the session they were built in, on the day they were built. A week later something is missing — an artifact that only existed in the chat window, a decision the agent made that can’t be reconstructed, a step that worked because the agent remembered context it no longer has.
The failure mode isn’t the agent being unreliable. It’s that the skill didn’t assign responsibilities clearly. When the agent holds the logic, the state, and the output all at once, the skill is only as durable as the conversation.
The framework here comes from building a release workflow skill: an AI agent skill that prepares staging release branches across a catalog of repos. A Brotli security patch needed to go into ten repos — same sequence every time, multiplied by ten. The skill automates that: determines which repos changed since the last release branch, cuts release-YYYY-MM-DD branches for each eligible one, and updates the k8s overlay with the new image tags. Examples in this post reference that context. The project is on GitHub at pikender/agent-skills, and the release workflow skill lives at .cursor/skills/release-workflow.
Table of contents
Open Table of contents
Flavors of Skills
Steve Kinney names four types by what a skill accomplishes in Agent Skills, Stripped of Hype:
- Knowledge — how we do it here; correct usage of internal libraries, APIs, conventions. Low-risk, overrides model defaults.
- Execution — ordered steps, scripts, tools orchestrated into a repeatable workflow. The agent follows a fixed path.
- Verification — prove correctness through testing or validation. Often paired with test harnesses.
- Automation — recurring business processes; results stored in files for consistency across runs.
He also notes that the best skills fit cleanly into one type — skills that straddle multiple types are usually a sign they should be split.
The release workflow in this post is an Execution skill: eligibility check, branch cut, k8s overlay update, in a fixed sequence. The agent follows the path; scripts do the work; humans review and decide when to push.
The five responsibilities below map most cleanly onto Execution and Automation skills — both involve deterministic steps and artifacts that need to outlive the session. Knowledge and Verification skills are simpler: fewer phases, less state to manage. But some things hold regardless.
What holds across all four types:
- SKILL.md should stay thin. Trigger, what to invoke, when to stop.
- Output should be files, not prose. Anything a human needs to act on later should exist in the repository, not the chat window.
- If there are phases, state files between them prevent the agent from assuming the previous step succeeded.
Five responsibilities. Each owned by exactly one component. None of them the agent’s in-session reasoning.
SKILL.md Owns the Flow
Trigger condition, commands to run in sequence, what each produces, when to stop. That’s it.
Not implementation details. Not how the commands work internally. When SKILL.md gets long, the agent fills gaps with its own reasoning instead of deferring to the script — and runs start diverging in ways that are hard to diagnose.
The test: someone who has never seen the skill should understand what it does and how to invoke it from SKILL.md alone. They should not need to read the script.
Scripts Own the Work
Every decision, every file modification, every git operation — in the script, not in the agent’s response.
The hard test: can you run it from the terminal, in a fresh session, and get the same result? If yes, the script owns the work. If no, the agent is holding part of the logic invisibly, and the skill breaks the moment that context is gone.
Scripts take all inputs explicitly — from arguments, config files, state files — never from the conversation. Given the same inputs and starting state, they produce the same outputs every time.
State Files Own the Trust
In a multi-step workflow, trust between steps is the central problem. The answer is not “the agent remembers.”
Each phase writes a state file on completion. Each subsequent phase checks that file before proceeding. cut refuses to run without eligible.txt. staging refuses until every eligible repo appears in cut-local.txt. The trust relationship is explicit and checkable.
One subtlety: state files need to record status, not just presence. A repo name in the file is less useful than a repo name with already-created and the branch. When status is only printed to the terminal, it vanishes. The file is the record.
Artifacts Own the Review
A skill that modifies real systems needs review before modifications become permanent. Review materials should be files in the repository — not text in the chat window.
Chat window output vanishes. It can’t be committed, diffed, or referenced when someone else needs to verify what happened.
In a release workflow: a branch log (git log --oneline <previous-release>...<new-branch> per eligible repo) and a delete script (git push origin :<branch> per pushed repo, not executed automatically). Both written by the script on every run — generated deterministically from state files, not composed by the agent.
The principle: anything the agent might say in a response that a human would need to act on later should be a file instead.
README Owns the Context
A run folder contains an input file, state files, a branch log, a delete script. For someone who was in the session, self-explanatory. For someone opening it cold — a week later, different machine, no session — a pile of files with non-obvious relationships.
The README makes the folder self-contained: what each file is, what the current state means, what actions are still available.
It is also written by the script on every run. Not hand-maintained. Generated fresh each time, reflecting actual current state. A hand-maintained README drifts from reality when the script changes. A generated README can’t.
The README is not documentation for the skill — SKILL.md is that. It’s documentation for the run: one specific execution, its state, and what can be done with it now.
When Responsibilities Collapse
Agent holds the flow instead of SKILL.md. Runs diverge — the agent fills gaps differently each time.
Agent holds the work instead of scripts. Skill breaks when the session ends. Terminal execution is impossible.
Agent holds the trust instead of state files. Reruns are unsafe. Idempotency depends on the agent’s memory.
Agent writes artifacts as prose. Review materials vanish when the chat closes.
No README. The run folder is opaque to anyone who wasn’t there.
Five Questions for a New Skill
- What is the flow? Write it in SKILL.md first. Trigger, command sequence, stop conditions.
- What is the work? Write a script. Verify it runs correctly from the terminal before connecting it to the agent.
- What needs to be trusted between steps? Design the state files before writing the phases.
- What does a human need to review before acting? Write those things to files from the script.
- What would someone need to know, opening this folder cold? Generate a README from the script that answers that for every run.
When all five answers live in the repository and not in the conversation, the skill works without the agent present, for someone who wasn’t in the original session, run from the terminal on a day no agent is involved. That’s the durability test.