Skip to content

All You Need Are Skill (Graphs)

Here's a problem you've probably hit.

You want an AI agent to do something non-trivial: pick up a GitHub issue, figure out what's wrong, write tests, fix the code, verify its own work, and merge. A real workflow with branches, loops, and the good sense to stop and ask a human when it's confused.

Source

The working skill files are in the all-you-need-are-skills repository.

So you look at frameworks. LangGraph gives you state machines with typed edges and durable execution. OpenAI's Agents SDK gives you explicit handoffs and context management. Serious tools, solving real problems. But notice what they're solving: they exist because models couldn't reliably follow multi-step instructions on their own. The typed edges, the state schemas, the checkpoint machinery: that's scaffolding for an agent you don't fully trust to stay on track.

Models are getting better. Fast. The gap between "needs a framework to sequence correctly" and "follows prose instructions reliably" is closing, and for many workflows it's already closed. If you've used a frontier model recently, you've felt this: the agent does what you asked, in order, without losing the thread. The scaffolding that was load-bearing two years ago is starting to become overhead.

I tried dropping the scaffolding and embracing markdown. The resulting technique, I've been calling skill graphs.

The stupid-simple version

Each markdown file describes one step of work. At the bottom, a line says which file to read next.

The agent reads a file, does what it says, follows the pointer. If the pointer branches ("if X, read file A; if Y, read file B"), the agent picks the branch. If the pointer loops back ("go fix it and come back"), the agent loops. If the pointer says "stop and ask the human," the agent stops.

This works because of what separate files give you that a single long prompt doesn't: isolation between branches. Picture a workflow where the agent audits its own work and the result can be "pass," "fail and retry," or "fail and escalate." In a single-document prompt, you describe all three paths. The agent reads the retry path and the escalate path before it even knows whether it passed. Add a second branch point and a loop, and you're five paragraphs into describing what happens when things go wrong. The agent starts preemptively following failure paths it hasn't reached yet, or gets confused about which branch it's on because it just read detailed instructions for three of them.

Separate files fix this. The agent reads the branch it's actually on. The retry path is in a different file. The escalation path is in a different file. This reduces cross-branch contamination. The agent isn't wading through detailed instructions for paths it won't take, which means it's less likely to follow them by accident and you're not burning context on hypotheticals. (Routing nodes like the audit phase do enumerate the branch labels and routing logic for each outcome, but the substantive work of each branch lives in its own file.)

Collectively, the files are a directed graph encoded entirely in prose, executed by an LLM that follows the pointers.

Why short files beat long prompts

Modern models handle long contexts well for retrieval, finding a needle in a haystack. But following instructions from a long document is different. When you hand a model 2,000 lines of detailed phase-by-phase instructions, the phases at the top get followed carefully. The phases in the middle get paraphrased. The phases at the bottom get creative interpretation. This is consistent with the "lost in the middle" phenomenon documented in retrieval tasks (Liu et al., 2023), though no controlled study has tested it specifically for instruction following. The effect is real in practice even if the research hasn't caught up.

Skill graphs address this with progressive disclosure. Each phase file is short (mine range from 7 to 67 lines, most under 35). When the agent reaches a new phase, it loads a fresh, focused set of instructions. The prior instructions are in the conversation history, but the instructional context for the current task is always a short, focused file rather than a 2,000-line document. The agent doesn't need to hold the whole workflow in its head because each phase operates on the outputs of previous phases (commits, test results, issue comments), not on their instructions. The conversation does grow with each phase. By phase 9, all prior outputs and tool calls are in the context window. The progressive disclosure benefit is relative: current instructions are always the freshest, but they compete with an increasingly long history.

You've seen this before

If this sounds familiar, it should. The progression from prompt to skill to skill graph follows the same path that software took from scripts to functions to programs.

Deep Skill Chaining (Bagaria & Konidaris, ICLR 2020) formalized graph-of-skills composition in reinforcement learning, with skills as options and composition as graph edges.

Prompt chaining: developers have been breaking long tasks into discrete prompt steps, where each step's output feeds the next, since at least 2023. Skill graphs are the next step in that progression: prompts became skills (reusable, parameterized instructions), and skills became graphs (branching, bounded cycles, typed inter-skill calls, parallel fan-out, and human escalation, all encoded in the same prose files the agent already reads, with no orchestration code).

LangGraph brought graph-based orchestration to LLM agents with typed state machines and durable execution. For systems where you need guaranteed sequencing today, it remains the right tool. What skill graphs offer is the same topology without the machinery: prose continuation pointers executed by a model that's reliable enough to follow them.

Why not a framework?

Frameworks solve a trust problem. When you can't rely on the model to follow a sequence of instructions faithfully, you need typed edges to enforce the transitions, state schemas to make sure data flows correctly between nodes, and checkpoint machinery to recover when the agent goes off the rails. That's good engineering. It was also necessary engineering, because until recently the models genuinely weren't reliable enough.

But that trust problem is shrinking. Every model generation follows instructions more faithfully, handles longer contexts more reliably, and makes fewer sequencing errors. The scaffolding that compensated for unreliable models is becoming weight you carry for its own sake.

I can iterate on a skill graph in minutes. The first version of my fix-issue skill had five phases. The second had seven. The current one has nine. I added a self-review phase after the agent kept submitting sloppy work. I added a risk assessment phase after it broke a production database schema. Each change was: write a new markdown file, update two continuation pointers.

With a framework, each change is: update the graph definition, make sure the state schema accommodates the new node, verify the typed edges still connect, rebuild, test. That rigor was the point when you needed the framework to enforce what the model couldn't do on its own. When the model handles sequencing reliably, the rigor is friction, and friction means you stop iterating.

Adding a phase requires no manifest update, just a new file and a pointer change. The skill's entry point (SKILL.md) does have YAML frontmatter that registers it with Claude Code, but the internal graph structure has no separate definition to maintain. Write phase-security.md, change one pointer in the preceding phase, add a pointer in the new file to the next phase. The continuation pointers are the edges, and they live in the nodes themselves. You edit the same artifact the agent reads.

And because skill files are just prose, the agent can write them too. I used Claude to author most of these skills in the first place, then iterated with it to optimize the phase boundaries for progressive disclosure. Claude Code has a built-in skill creation mechanism, so the agent can extend its own graph: add phases, split a phase that's doing too much, write a new reviewer role for the fan-out.

What the graph looks like

This repo includes two skills that I use together to take a GitHub issue from "open" to "merged": fix-issue and audit-issue. They're good examples of what a skill graph looks like in practice, so I'll walk through them here.

You never need to draw this diagram. The prose files are the graph. I'm drawing it so you can see the topology all at once, but the diagram is a visualization aid, not an artifact you maintain.

The left side is fix-issue: a nine-phase chain. The right side is audit-issue: a five-phase sequence whose central phase fans out to two parallel reviewers that synthesize a verdict.

Skill graph topology: fix-issue and audit-issue

Five kinds of edges make this work.

Sequences are the straight arrows. Each phase file ends with a pointer to the next file. One pointer, one destination. The exact wording doesn't matter; the agent follows any clear prose instruction to read a specific file.

Cycles with guards are the dashed arrows going backward. When the audit returns PARTIAL, the agent loops back to fix, then re-audits. But only twice. After that, it escalates. The guard is a sentence in the prose. In my experience, the model has respected the two-retry limit reliably across dozens of runs, though I haven't measured this formally.

Typed inter-skill calls cross skill boundaries. fix-issue calls //audit-issue $0 (a Claude Code skill invocation) and routes on the return value: COMPLETE, PARTIAL, or WRONG DIRECTION. There's no type checker, just an enumerated return contract in prose that both skills agree on. See the call in phase-audit.md and the contract in audit-issue/SKILL.md. The //skill-name syntax is specific to Claude Code; if you're using a different tool, replace it with whatever mechanism your tool provides for invoking a sub-prompt or sub-agent.

Parallel fan-out with restricted tool access is the diamond. audit-issue launches two concurrent reviewers, an intent reviewer and a factcheck reviewer, each restricted by their role prompt to file inspection tools plus Write. In Claude Code, the agent launches parallel subagents by issuing multiple tool calls in a single response. The tool restriction is prompt-level, not sandbox-enforced. The separation matters because the reviewers are adversarial, and you don't want them running the tests they're supposed to be reviewing.

Human escalation is the orange node. Ambiguous intent, repeated audit failure, design disagreements, pre-merge confirmation. In each case the agent halts, preserves state, and waits. Some decisions shouldn't be automated. Making that explicit in the graph topology is how you keep the agent from doing something regrettable at 3 AM.

Build one in ten minutes

You don't need my skills. You need the pattern. If you've ever read a Choose Your Own Adventure book, you already understand the structure: a page of instructions, then a pointer to the next page. Swap "page" for "markdown file" and "reader" for "LLM" and you're there.

Step 1. Pick a workflow you do repeatedly. Doesn't have to be code: could be research, writing, data pipeline debugging, anything with steps.

Step 2. Write each step as a short markdown file. Describe what to do, what "done" looks like, and what to read next. Keep each file under 50 lines. Here's a complete phase file for a code review workflow:

# Phase: Check Test Coverage

Review the diff for any changed functions that lack test coverage.

For each untested function:
1. Note the function name, file, and what it does.
2. Write a test that covers the happy path.
3. Run the test suite to confirm it passes.

**Done when:** Every changed function has at least one test, and the suite is green.

**Next:** Read `phase-style-check.md` in this directory.

Step 3. At the bottom of each file, add a continuation pointer. For branches:

If the tests pass, read `phase-deploy.md`.
If the tests fail, read `phase-debug.md`.
If you've failed and retried twice, read `phase-escalate.md`.

That's a skill graph. A few markdown files, linked by prose pointers. Run it with whatever LLM-powered tool you use. If you want to see what a more complex one looks like, the skill files in this repo are adapted from a working codebase. Start with the phase files, which are all under 70 lines and show the pattern clearly.

What's next

I've been building TeaParty as a testbed for multiagent workflows, and skill graphs are becoming load-bearing. Over 250 issues on that project have been closed using some version of these skill graphs: investigating, branching, fixing, testing, auditing, and merging with minimal human intervention. The architecture I'm converging on has two speeds: a slow path where multiple agents deliberate, research, and argue about the approach, and a fast path where a proven workflow executes without deliberation. The slow path burns tokens and time, but it's how you solve problems you haven't seen before. The fast path, a skill graph, runs a pre-compiled procedure. The thinking already happened when someone wrote the phase files.

The bridge between the two is where it gets productive. When the slow path cracks a problem, that solution should crystallize into a skill graph so no agent ever has to re-derive it.

Failure is the strongest learning signal I've found so far. When an agent hits something unexpected (a flaky test suite, a merge conflict, a dependency that vanished overnight), that's the graph telling you where it needs a new branch. The first time, the agent improvises. You watch it struggle, and then you (or the agent, with your review) write phase-flaky-tests.md with a continuation pointer back to the main flow. The graph grows at the points where it broke, which means it grows in exactly the places that matter.

The open problems are real: self-modifying workflows can reward-hack themselves into nonsense, graphs can grow without bound, new branches can silently break patterns that used to work, and observability for graph transitions (not just individual phases) is unsolved. Claude Code has telemetry and Anthropic has published guidance on iterating skills, but whether that scales to skill graphs remains open. I'll write about what works and what doesn't.


Skills: fix-issue/ and audit-issue/. Questions, corrections, and "this broke when I tried it" reports are welcome as issues.

Comments & reactions