small-briefs
Skill0 starsChanged 8 days agoMITView on GitHub
Split a big build into small, self-contained briefs for a coding agent, run them in sequence, and verify each piece before sending the next. Use when delegating a multi-part build to a coding agent (opencode, Claude Code, Codex), when a task has many steps or many files, or when the user says "break this down", "pecah tugas ini", "delegasikan", "brief untuk opencode", "kerjakan bertahap". Do NOT use for a single small change that fits in one instruction.
In this repository15 other files it gives its agents.
- cloudflare-workerSkill
- oss-contributorSkill
- councilSkill
- title-cardSkill
- repo-auditSkill
- vps-deploySkill
- interactive-figureSkill
- lab-reportSkill
- net-labSkill
- study-notesSkill
- vault-routerSkill
- html-videoSkill
- manim-explainerSkill
- caption-craftSkill
- proofread-idSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Every brief is self-contained.
- Distinctive: line 74
Report per piece: After each brief: what was checked, what passed, what is next.
- Distinctive: line 84
If the same piece fails twice at the same size, the brief itself is probably ambiguous or overloaded.
- Distinctive: line 90
Not a project plan. It does not decide what to build.
- Distinctive: line 92
Not a reason to fragment trivial work.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Small Briefs
A coding agent given one giant brief does not fail loudly. It stalls: the process looks alive, the log looks calm, and nothing comes out. This happened twice in one day on a real project, on a run of 100+ generation tasks handed over at once. The same work, split into small sequential briefs with a check after each one, finished the same evening. This skill is that splitting discipline. It exists because the giant brief is the most expensive way to discover it.
The rule
One brief, one outcome, one verification. A brief is done when its finish line is visible in the real artifact, not when the runner reports healthy signals.
What a brief contains
Every brief is self-contained. The agent receiving it has none of your conversation, so each brief carries:
- The outcome, in the user's terms: what exists when this piece is finished.
- The exact constraints: paths, ports, names, versions, limits, the choices already made. Nothing the agent would have to guess.
- The finish line: the check that proves it worked, for example a file that exists with specific content, an endpoint that answers, a test that passes, a number that matches.
- What is out of scope for this piece, so the agent does not wander into the next piece or rebuild a finished one.
Long briefs go in a file the agent reads, not pasted as a wall of text. Anything a human must copy by hand stays short and single-line.
How to split
- Cut at verification seams. Each brief ends somewhere you can check independently: a scaffold that runs, one feature that works, one batch of assets that exists. If you cannot describe the check, the cut is in the wrong place.
- Batch size is a safety limit, not a target. For bulk generation (assets, files, near-identical items), about 20 per brief is the proven ceiling in this workflow; 100+ in one brief is the documented stall. When a run stalls, do not resend the same brief bigger or louder. Halve it.
- Order by dependency, run in sequence. Brief N+1 is written after brief N's check passes, and may depend on what N actually produced, which is often not quite what the plan assumed.
- Parallel only when the road is proven. Truly independent briefs may run in parallel only on infrastructure already shown to hold under load. On a fragile route, parallel runs corrupt each other: outputs mix, gateways fall over, and the failure looks like a model problem when it is a load problem. Serial is slower and finishes.
Running the pieces
- Launch long runs supervised. A backgrounded agent process can die silently a minute in, leaving a clean-looking log. Use the platform's supervisor (a systemd unit, a task runner, a session manager) so the run outlives the shell that started it.
- Wait on the supervisor's state, not on text matching. Polling a process list for words from the brief matches the waiter's own command line and hangs forever. Poll the unit's active state, the output file's growth, or the finish line itself.
- Verify before you celebrate, and before the next brief. Open the artifact, run the check, compare the number. A successful launch, a running process, and a calm log are none of them evidence.
- Report per piece. After each brief: what was checked, what passed, what is next. The human should never have to ask whether piece 3 of 7 is done.
When a piece fails
- Name the stall fast. A run that produces nothing is a failed brief, not a slow one; switch method instead of waiting it out.
- Shrink and retry the piece, not the whole job. Finished pieces stay finished.
- If the same piece fails twice at the same size, the brief itself is probably ambiguous or overloaded. Rewrite it smaller and more explicit before spending a third run.
What this skill is not
- Not a project plan. It does not decide what to build; it decides the size of the pieces a decided build is handed over in.
- Not a reason to fragment trivial work. A one-line fix gets a one-line brief.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

