shape-work
Skill0 starsChanged 16 days agoMITView on GitHub
Turn a vague request into a scoped task with in/out of scope and yes/no acceptance. Use when the user says shape this, scope this, stress-test the plan, or pastes a rough ask. Do not write product code. Do not start the first slice unless they asked to implement too.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- rpraharaj/ai-engineertheir own version, first seen Nov 1, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- rpraharaj/ai-engineer★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository66 other files it gives its agents.
- AGENTS.mdAGENTS.md
- a11y-passSkill
- assess-changeSkill
- build-regression-packSkill
- charter-exploratorySkill
- classify-dataSkill
- commitSkill
- cut-releaseSkill
- data-changeSkill
- debugSkill
- design-experimentSkill
- diff-environmentsSkill
- draft-steercoSkill
- engineering-barSkill
- explain-codeSkill
- explore-codebaseSkill
- fix-ciSkill
- handoffSkill
- implement-changeSkill
- incident-triageSkill
- lean-reviewSkill
- map-dependenciesSkill
- map-design-handoffSkill
- map-processSkill
- open-prSkill
- performanceSkill
- plan-data-migrationSkill
- plan-incrementSkill
- plan-rollbackSkill
- plan-uatSkill
- prioritize-backlogSkill
- production-passSkill
- ready-to-mergeSkill
- record-decisionSkill
- refactor-safelySkill
- revert-changeSkill
- review-architectureSkill
- review-changeSkill
- review-pipelineSkill
- security-passSkill
- ship-notesSkill
- spec-analyticsSkill
- spec-observabilitySkill
- start-projectSkill
- synthesize-discoverySkill
- triage-blockersSkill
- triage-defectSkill
- update-raidSkill
- verify-uiSkill
- write-api-examplesSkill
- write-architectureSkill
- write-designSkill
- write-dev-tasksSkill
- write-docsSkill
- write-integration-contractSkill
- write-nfrSkill
- write-opportunitySkill
- write-prdSkill
- write-requirementsSkill
- write-runbookSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
If kind is incident or greenfield, stop and run that skill.
- Very specific: line 36
If kind is change, several decisions are open, and they asked to think it through, prefer write-prd or write-design over a one-shot shape.
- Distinctive: line 50
Read AGENTS.md. Skim only the files needed to name a real approach.
- Distinctive: line 53
Write the document from references/shaped-work-template.md.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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
Shape work
Turn the ask into a task another session can implement without guessing. Do not edit product code.
Is this the right skill?
| Signal | Do this instead |
| Stack trace / “broken” | debug (shape the repro; do not skip it) |
| Production down / wrong data in prod | incident-triage |
| Empty tree / no app | start-project |
| What / why for users | write-prd |
| Durable system shape | write-architecture |
| How this initiative is built | write-design |
| Ticket list | write-dev-tasks |
| How does this code work | explain-code — no fake task |
| README / API / runbook only | write-docs |
| Pure question | Answer; no fake task |
If kind is incident or greenfield, stop and run that skill. If the workspace is only README / LICENSE / .gitignore / AGENTS.md, treat as greenfield.
If kind is change, several decisions are open, and they asked to think it through, prefer write-prd or write-design over a one-shot shape.
Required inputs
- The user’s ask
AGENTS.mdif present. If the change is more than a few lines and the repo is unmapped, runexplore-codebaseor say knowledge is incomplete.
Human decisions (do not invent)
- Product forks (who it is for, contradicting goals)
- Whether a smaller reuse option is enough
Procedure
- Read
AGENTS.md. Skim only the files needed to name a real approach. - Decide the kind (table above). Ask at most a few blocking questions. Non-blocking go in the doc.
- Large ambiguous change: decision pass — frontier questions with recommended answers; wait; do not invent lookup-able facts.
- Write the document from references/shaped-work-template.md. Every acceptance check is yes/no. No “works well.”
- Save a file only if the user asked or the repo already keeps shapes (
docs/tasks/). Otherwise print it.
Output
- Path: reply, or
docs/tasks/<slug>-slice.md - Template:
references/shaped-work-template.md
Quality bar
- Out of scope is non-empty unless the ask is tiny
- At least one acceptance check would fail today (change/defect)
- First slice is smaller than the whole goal when there is more than one risk
- Likely files are real paths or you say you could not find them
Done
- The shaped work
- Next skill — do not implement unless they said shape and implement and slice 1 is fully specified
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.