agentleFS
Sign inStart free
ambient-codeambient-code/platform/skills/spec/SKILL.md

spec

Skill131 starsChanged 6 months agoMITView on GitHub

Create or modify a spec following the project's spec format and conventions. Use when the user wants to write a new spec, add requirements or scenarios to an existing spec, or restructure spec content. Triggers on: "write a spec", "create a spec", "add a requirement", "spec this out", "define the behavior", "what should the spec look like", "new spec for", "update the spec".

168 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use backprop, ios-clean and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JuliusBrusseeSkill

    backprop

    Bug → spec protocol. When a bug is found or a test fails, trace the cause, decide whether a new §V invariant would catch recurrence, append to §B. This is the one non-obvious thing SDD does that plan-then-execute doesn't. Triggers on test failure, bug report, post-mortem, or explicit user ask.

    Also in 4 projects that use this

  • Saqlain-811Skill

    ios-clean

    Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app. (gstack)

    Also in 5 projects that use this

  • Saqlain-811Skill

    ios-fix

    Autonomous iOS bug fixer. (gstack)

    Also in 5 projects that use this

  • bastosSkill

    ios-design-review

    Review iOS app UI/UX design quality using Apple's design principles and the Liquid Glass-era design language from WWDC25/26. Use when asked for a design review, UX critique, visual design assessment, or evaluation of an app's interface quality, design intent, alignment with the new Apple design system, or usability. Triggers: "design review", "UX review", "visual design critique", "review the UI", "does this design work", "evaluate this interface", "design feedback", "Liquid Glass review".

    Also in 5 projects that use this

  • ShreyRaviSkill

    plan-tune

    Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences (never-ask / always-ask / ask-only-for-one-way), inspect the dual-track profile (what you declared vs what your behavior suggests), and enable/disable question tuning. Conversational interface — no CLI syntax required.

    Also in 7 projects that use this

  • timurgaleevSkill

    document-generate

    Generate missing docs for a feature, module or project as tutorials, how-tos, reference and explanation.

    Also in 6 projects that use this

  • +2 more from Saqlain-811

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 8 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 145 edited versions we read keep these.

  • 8

    Distinctive

    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 these two files in full before proceeding:

    line 23
  2. Distinctive:

    Desired state only: Ask the user what the system should do, not what's currently broken.

    line 36
  3. Distinctive:

    Reserved terms check: Verify no collision with Ambient domain model terms (Inbox, Session, Agent, Project, Credential, SessionMessage, etc.)

    line 38
  4. Distinctive:

    Read actual code and existing specs in the affected areas.

    line 42
  5. Distinctive:

    Read existing specs in the target domain

    line 44
  6. Distinctive:

    Ask only where the codebase doesn't give a clear answer

    line 47
  7. Distinctive:

    Do not proceed to drafting until the user confirms.

    line 49
  8. Very specific:

    Follow the format from specs/index.spec.md:

    line 53
  9. Distinctive:

    If the spec exceeds ~300 words or covers multiple distinct topics, split into a directory with multiple files

    line 81

“Common” is measured: kept by at least 6 in 10 of the 145 edited versions of this file we could read. “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

Write or Modify a Spec

Help the user create or change a spec that describes desired system behavior.

User Input

$ARGUMENTS

Before Anything Else

Read these two files in full before proceeding:

  1. specs/index.spec.md — what a spec is, the required format, naming conventions, and what does and does not belong
  2. workflows/specs/spec-change.workflow.md — the full spec change workflow (framing, grounding, drafting, critic passes, synthesis)

Then follow the workflow phases in order.

Steps

Phase 1 — Frame

Establish the framing before writing anything:

  • Desired state only. Ask the user what the system should do, not what's currently broken. If they describe a bug, redirect: "What should the correct behavior be?"
  • Scope boundary. Which components does this change touch? (schema, gRPC, runner, operator, CLI, frontend, SDK, RBAC)
  • Reserved terms check. Verify no collision with Ambient domain model terms (Inbox, Session, Agent, Project, Credential, SessionMessage, etc.)

Phase 2 — Ground in the codebase

Read actual code and existing specs in the affected areas. Confirm your understanding without wasting the user's time:

  • Read existing specs in the target domain
  • Grep the components identified in Phase 1
  • Summarize back in 3–5 sentences: what you found, what you believe they want, what's ambiguous
  • Ask only where the codebase doesn't give a clear answer

Do not proceed to drafting until the user confirms.

Phase 3 — Draft the Spec

Follow the format from specs/index.spec.md:

  • Purpose section — one paragraph describing the domain or feature
  • Requirements — each states an observable behavior using RFC 2119 keywords (SHALL, MUST, SHOULD, MAY)
  • Scenarios — concrete Given/When/Then examples for each requirement that could be turned into tests

Include: data model, write paths, read paths, RBAC, migration plan for all existing consumers.

Phase 4 — Critic Pass

Spawn critics in parallel per the workflow. Standard critics (every spec change):

  • Schema / migration
  • RBAC / auth
  • Ambient terminology

Plus scope-driven critics based on the components identified in Phase 1.

Phase 5–6 — Synthesize and Present

Separate findings into factual errors (fix directly) and design decisions (present to user with 2–3 concrete options each, one at a time).

Phase 7 — Apply and Verify

Apply all fixes. Run a second critic pass (Phase 8). Stop when only MINORs remain.

Final — Name and Place the File

  • Filename: <descriptive-title>.spec.md
  • If the spec exceeds ~300 words or covers multiple distinct topics, split into a directory with multiple files
  • Place in specs/{domain}/

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