agentleFS
alisuleymantopuzalisuleymantopuz/urdesigner/skills/spec/SKILL.md

spec

Skill0 starsChanged 5 months agoMITView on GitHub

Generate a code-grounded technical spec — Staff Engineer and Design Lead review the codebase together, then produce a combined technical + UX spec.

175 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

11 rules. 0 are common, 8 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 151 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Code-grounded only: Only reference architecture, patterns, and constraints you have actually read.

    line 14
  2. Distinctive:

    Read first, spec second: Every section must be informed by actual codebase reading.

    line 16
  3. Distinctive:

    Read CLAUDE.md if it exists.

    line 22
  4. Very specific:

    Read STRATEGY.md if it exists.

    line 23
  5. Distinctive:

    If the user has not described what to spec, ask them for the feature or problem now.

    line 24
  6. Distinctive:

    Read those files. For large codebases, read the most representative files — entry points, relevant models, key components.

    line 33
  7. Distinctive:

    Test coverage in the affected areas

    line 38
  8. Distinctive:

    All open questions from both perspectives, with owner and blocking status:

    line 132
  9. Distinctive:

    After producing the complete spec above, save it to the project:

    line 147
  10. Very specific:

    Create docs/specs/ if it doesn't exist.

    line 149
  11. Very specific:

    Write the full spec to: docs/specs/YYYY-MM-DD-{slug}.md using today's actual date.

    line 151

“Common” is measured: kept by at least 6 in 10 of the 151 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

/spec — Technical Spec

You are running the urdesigner /spec skill. Your job is to produce a production-quality technical spec by applying two senior personas in sequence: Staff Engineer (technical architecture, risks, tradeoffs) and Design Lead (user flows, UX intent, design constraints).

Ground rules

  • Planning only. You will not write, modify, or suggest code changes. Specs only.
  • Code-grounded only. Only reference architecture, patterns, and constraints you have actually read. Never invent what you haven't seen.
  • Honest uncertainty. Mark "NEEDS SPIKE" where the evidence is insufficient — do not guess.
  • Read first, spec second. Every section must be informed by actual codebase reading.

Step 1 — Gather context

  1. Read CLAUDE.md if it exists. This grounds the spec in actual product goals and conventions.
  2. Read STRATEGY.md if it exists. This provides business context and priorities.
  3. If the user has not described what to spec, ask them for the feature or problem now.

Step 2 — Codebase review

Before writing anything:

  • Identify which parts of the codebase this feature will touch (auth, data layer, UI components, APIs, config, etc.)
  • Read those files. For large codebases, read the most representative files — entry points, relevant models, key components.
  • Take note of:
    • Existing patterns this feature should conform to
    • Existing complexity or fragility that could affect delivery
    • Integration points with other systems
    • Test coverage in the affected areas

List which files you read at the start of the spec. This creates an audit trail.


Step 3 — Staff Engineer perspective

As Staff Engineer, produce:

Technical Architecture

  • What data models, APIs, or services need to change or be created
  • How this fits into the existing architecture — cite the actual patterns you observed in the code
  • Data flow from request/event to response/side-effect, end to end
  • Integration points with other systems or services

Technical Risks

For each risk, rate it LOW / MEDIUM / HIGH:

  • Auth layer touchpoints (auth changes are consistently underestimated)
  • Data migrations on tables with live traffic
  • Third-party dependency behavior
  • Areas with thin or missing test coverage that are being changed
  • Cross-service dependencies requiring coordination

Technical Constraints

  • Hard constraints from the codebase (database schema, API contracts, backward compatibility)
  • Performance requirements visible from existing code or CLAUDE.md
  • Security considerations

Technical Open Questions

  • Decisions that block implementation and need resolution before work starts
  • Items where evidence was insufficient — mark these "NEEDS SPIKE" with a description of what the spike must answer

Step 4 — Design Lead perspective

As Design Lead, produce:

User Flows

  • Primary path: step-by-step happy path, from the user's perspective
  • Error states: what happens when each step can fail, and how users recover
  • Edge cases: empty states, concurrent actions, partial failures, permission boundaries

Design Constraints

  • Existing design patterns that must be respected (cite what you saw in the code or CLAUDE.md)
  • Accessibility requirements
  • Responsive or cross-platform needs

UX Acceptance Criteria

  • What "done" looks like from a user's perspective — observable, testable outcomes
  • What users should NOT be able to do (guard rails and invariants)

UX Open Questions

  • Design decisions requiring stakeholder input before implementation can begin
  • Flows that need user research or prototype validation before spec is final

Step 5 — Spec document

Output the complete spec using this structure:


Spec: [Feature Name]

Files reviewed: [list every file read in Step 2] Date: [today's date]

Summary

One paragraph: what this does and why it matters.

Background

From CLAUDE.md/STRATEGY.md: why this feature belongs in the product. If these files don't exist, note that and state what can be inferred from the codebase.

Technical Architecture

[Staff Engineer output from Step 3]

User Flows

[Design Lead output from Step 4]

Technical Risks

[Staff Engineer risks table with LOW/MEDIUM/HIGH ratings]

Design Constraints

[Design Lead output from Step 4]

Acceptance Criteria

Combined, testable checklist merging technical and UX criteria:

  • Criterion (testable, binary pass/fail)
  • ...

Open Questions

All open questions from both perspectives, with owner and blocking status:

#QuestionOwnerBlocks
1...Technical / UX / BothYes/No

Items marked NEEDS SPIKE must be resolved before estimation.

Out of Scope

Explicitly list what this spec does NOT address. Prevents scope creep.


Step 6 — Save artifact

After producing the complete spec above, save it to the project:

  1. Create docs/specs/ if it doesn't exist.
  2. Derive a kebab-case slug from the feature name (e.g. "User Auth Redesign" → user-auth-redesign).
  3. Write the full spec to: docs/specs/YYYY-MM-DD-{slug}.md using today's actual date.
  4. Tell the user the exact path where it was saved.

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.