agentleFS
Sign inStart free
codeboehmcodeboehm/maxim/skills/rework/SKILL.md

rework

Skill0 starsChanged 4 months agoMITView on GitHub

Revise an existing planning artifact — a structured prompt, a specification, or an implementation plan — addressing concrete feedback. Always clarifies the rework task via prompt first, then delegates to the matching skill (specify for a spec, implement for a plan) to redo it to the senior bar. Use when asked to rework/revise/fix an existing prompt, spec, or plan.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. marcuskrogh/skills★ 1same name
    2. jam7/ai-dev-gates★ 0same 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 repository8 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 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.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When this skill is invoked, you are revising an existing artifact, not starting from scratch and not implementing.

    line 6
  2. Very specific:

    Read the target and its lineage: Read the artifact and identify its type (by location and content).

    line 23
  3. Very specific:

    Clarify the rework with prompt (always first): Run it to capture *what* about the artifact must change, *why*, the constraints, and the …

    line 28
  4. Very specific:

    Inherit the downstream gates: Stop where the delegated skill stops (specify: after the spec.

    line 52
  5. Distinctive:

    Traceability: Keep the prompt ↔ spec ↔ plan names aligned so the revised artifact stays linked to its lineage.

    line 70
  6. Very specific:

    Always run prompt first; then delegate to specify (spec) or implement (plan), reusing that prompt — never double-run prompt.

    line 76

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

When this skill is invoked, you are revising an existing artifact, not starting from scratch and not implementing. First make the rework task explicit, then hand it to the skill that owns that artifact type.

Input

A path to an existing artifact:

  • a structured prompt — .agents/prompts/… (a <task_spec> XML block for Mistral, or the equivalent Markdown sections for other agents)
  • a specification — .agents/specs/… (a # Spec: document)
  • an implementation plan — .agents/plans/… (a # Implementation Plan: document)

…plus the user's rework intent (what's wrong / what to change). If no path is given or its type is unclear, ask — don't guess which artifact is meant.

Procedure

  1. Read the target and its lineage. Read the artifact and identify its type (by location and content). Follow its links — a spec's Source prompt, a plan's Spec. Understand the original intent before changing it. Run skills/index/query.sh to get the lineage's slugs and paths without opening every file in each artifact directory to find them.
  2. Clarify the rework with prompt (always first). Run it to capture what about the artifact must change, why, the constraints, and the acceptance criteria for the rework itself. Feed it the existing artifact and any review feedback as context. This must write a new clarified prompt file to .agents/prompts/ (a fresh date +%s name) — never skip it or reuse an earlier prompt. Resolve its open questions and wait — a rework with a vague goal ("make it better") is not ready to execute.
  3. Delegate to the matching skill — reusing the prompt from step 2. You have already run prompt; when you follow the skill below, start at the step that consumes the structured prompt — do not invoke prompt again.
    • Target is a spec → follow the specify skill: re-verify against current code, then rewrite the spec to its senior bar, addressing the rework.
    • Target is a plan → follow the implement skill from its planning step: re-verify the spec, then rewrite the plan, addressing the rework; honor its review and confirmation gates.
    • Target is a structured prompt → the clarified prompt from step 2 is the reworked prompt; update the target file with it. If the user wants to go further, hand off to specify.
  4. Update in place. Rework the existing artifact at its current path/slug — do not spawn a parallel copy (that fragments prompt ↔ spec ↔ plan). Note what changed and why (in the handoff, or a short "Revised:" line at the top). Then run skills/index/reindex.sh — the revised artifact's Status/Date may have changed.
  5. Inherit the downstream gates. Stop where the delegated skill stops (specify: after the spec; implement: plan-approval, then explicit start-implementation). Never auto-commit.

The senior bar (non-negotiable)

  • Fix the named gaps; keep what was right. Address the concrete feedback — don't rewrite wholesale and don't discard sound prior decisions. If the rework request is vague, the prompt step must pin it down before you act.
  • Re-verify against current code. Artifacts drift from the code after they're written; re-check every fact the revision depends on (path:line), and use the analyze skill's live access where the project offers it. Read .agents/project.md for the operational ground truth (stack, commands, invariants); if it looks stale against the current repo, flag it or refresh it via orient before relying on it.
  • Apply the delegated skill's full bar — verification, threat-model calibration, project invariants, precise non-destructive edits, testable acceptance criteria. Rework is not a shortcut around quality.
  • Traceability. Keep the prompt ↔ spec ↔ plan names aligned so the revised artifact stays linked to its lineage.

Rules

  • Requires a path; if missing or its type is ambiguous, ask before proceeding.
  • Always run prompt first; then delegate to specify (spec) or implement (plan), reusing that prompt — never double-run prompt.
  • Revise the artifact in place at its existing location; don't create a duplicate.
  • Honor the delegated skill's stop-for-review gates. Never commit or push.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free