An engineering orchestrator agent had four core workflows: break down tasks, spawn subagents, monitor progress, and review PRs. All four were documented in a single 400-line config file, mixed in with correction logs, messaging rules, and infrastructure notes.
Every workflow worked. But finding the steps for “how to spawn a subagent” meant scanning past QA review protocols, message format specs, and three correction entries about posting to the wrong channel. When Mel hit context compaction, the procedures she needed most were buried in the middle of the file — competing for space with identity statements she had already internalized.
The Problem
Agent config files grow organically. You start with identity and rules. Then you add a procedure for handling tasks. Then another for PR review. Then a correction log entry. Then an infrastructure note. Before long, the file is doing two jobs: telling the agent who it is, and telling it how to do specific things. These are fundamentally different concerns, but they live in the same document because that’s where you were writing when you figured out the procedure.
The consequences are subtle but real:
- Procedures compete for context space. A 400-line config file where 300 lines are procedures means the agent loads 300 lines of “how to” instructions on every session — even when it only needs one of those workflows.
- Procedures are hard to find. “How do I spawn a subagent?” is a question with a specific answer, but it’s not indexed, not searchable by name, and not invocable as a command.
- Procedures drift. When a procedure is a section in a larger file, updates are easy to miss. When it’s a standalone skill, it’s obvious when it’s stale.
- Procedures can’t be tested independently. You can’t run an eval against “section 4 of AGENTS.md.” You can run one against a skill.
Why This Happens
Config files are the first thing most agent frameworks tell you to create. They’re the natural home for everything the agent needs to know. And for identity, rules, and behavioral corrections, they’re the right home — those things are always relevant and should always be in context.
But procedures are different. A procedure is a recipe: “when this trigger happens, follow these steps.” It has a defined scope, a clear start and end, and it’s only relevant when that trigger fires. That’s exactly what a skill is.
The Fix
Take each procedure in your config file and ask: does this have a trigger, discrete steps, and a defined output? If yes, extract it into a skill.
Before: procedure buried in config
# AGENTS.md (line 274 of 405)
## QA Review Step
Every PR goes through review before it reaches the human...
### When a coding agent completes a task and CI is green:
1. Spawn a review subagent in the same worktree
2. If review approves, create PR, post to channel, notify the chief of staff
3. If review requests changes, re-spawn coding agent with feedback
4. Max 2 review cycles before escalatingAfter: standalone skill
# skills/pr_review/SKILL.md
---
name: pr_review
description: "Run QA review on completed work, create a PR,
and notify the chief of staff. Use when a subagent finishes
a task and CI is green."
---
## Prerequisites
- Subagent has completed work (phase: done, verification passed)
...
## Step 1 — Verify CI passes
...
## Step 2 — Spawn review
...The config file gets a one-liner: “PR review is handled by the /pr_review skill.” The procedure lives in its own file with a clear trigger, structured steps, and a description that tells the agent when to reach for it.
What stays in config
Not everything should be a skill. Keep these in the config file:
- Identity: who the agent is, what it values, its tone
- Rules: behavioral constraints, safety boundaries
- Correction logs: lessons from past mistakes (these inform all behavior, not just one workflow)
- Routing tables: which model for which task type
- Infrastructure notes: paths, URLs, credentials references
The test is simple: if it’s always relevant regardless of what the agent is doing right now, it belongs in config. If it’s a recipe for a specific situation, it’s a skill.
The payoff
After extracting four procedures from Mel’s 400-line config, the config dropped to ~150 lines of identity, rules, and corrections. Each procedure became a self-contained skill that:
- Triggers reliably — the description tells the agent exactly when to use it
- Loads only when needed — no wasted context tokens on procedures that aren’t relevant
- Can be improved independently — update the PR review process without touching identity docs
- Can be audited — skills are listed in the directory, not buried in prose
The extracted skills mapped directly to Mel’s core loop: /breakdown for planning work, /farm for spawning subagents, /monitor for tracking progress, and /pr_review for running Roberto’s QA step and creating PRs. Each one references the existing infrastructure — the loop scripts, task templates, status files — without duplicating them.
Key Takeaway
Your agent’s config file should answer “who are you?” Your skills should answer “how do you do this specific job?” When those two questions are answered in the same document, both answers get worse. The config becomes bloated, the procedures become hard to find, and the agent wastes context on instructions it doesn’t need right now. Separate them and both get better.