agentleFS
Cody-SimsCody-Sims/agent-skills/skills/requirements-and-spec-writing/SKILL.md

requirements-and-spec-writing

Skill0 starsChanged 4 months agoMITView on GitHub

Turns unclear requests into agreed, testable specifications before implementation. Use when a request is vague or large, scope/acceptance criteria are unclear, or a spec, requirements, or design is requested; not for decomposing an approved spec or a small well-defined edit.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read applicable instructions and relevant existing code/documents to identify constraints.

    line 25
  2. Distinctive:

    When drafting, read the spec template and use its section order.

    line 29
  3. Very specific:

    Check section completeness, requirement-to-criterion coverage, constraints, explicit non-goals/assumptions/open questions, and required …

    line 44
  4. Distinctive:

    Stop at the specification handoff, not coding or delivery planning.

    line 54

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

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

Requirements and Spec Writing

Contract

Inputs: the original request/context and any existing-system constraints. Output: a requester-agreed specification, or an explicitly unapproved draft with open decisions. This skill does not authorize implementation or task execution.

Workflow

  1. Restate the intended outcome and boundaries. Confirm the restatement from supplied agreement or with the requester before proceeding; do not ask them to repeat decisions already confirmed. If interaction is unavailable, label any draft unapproved and do not treat assumptions as consent.
  2. Read applicable instructions and relevant existing code/documents to identify constraints. Begin with named interfaces, use cases, and known paths; widen scoped searches only for a specific unanswered question. No full architecture audit or automatic worker launch is needed to clarify a bounded request.
  3. When drafting, read the spec template and use its section order. Cover objective, users/use cases, functional/non-functional requirements, non-goals, existing constraints, interfaces/data contracts, security/privacy, error/edge cases, acceptance criteria, open questions, alternatives, and rollout/rollback. Return inline unless a file is requested or repository conventions require one; do not create extra planning artifacts.
  4. Label facts with sources, minor assumptions explicitly, and consequential unknowns as open decisions with owners. Ask one focused consequential question at a time only when context cannot answer it; batch trivial confirmations. Move scope expansion into non-goals or follow-up instead of silently adding it.
  5. Make every requirement testable and pair it with observable acceptance criteria. Record rejected alternatives and reasons. Address security, privacy, trust boundaries, invalid/empty inputs, limits, and failure behavior, or explicitly identify the missing decision. Never invent requester-owned policy, authorization, data-retention, or rollout choices.
  6. Check section completeness, requirement-to-criterion coverage, constraints, explicit non-goals/assumptions/open questions, and required repository spec gates. Validate against the gathered context; do not run unrelated builds or tests just to produce a specification.
  7. Present for agreement. Resolve consequential open questions or obtain explicit agreement to carry them forward before implementation. Keep an unapproved draft separate from an agreed specification; lack of a reply is not approval.

Stop and output

Stop at the specification handoff, not coding or delivery planning. If context, interaction, or approval is missing, return a draft and name the blocker. Report the specification, agreement status, brief assumptions with sources where available, and open decisions/owners needed before implementation. Claim ready only when required checks and requester agreement are evidenced.

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.