User Story Writer
deanpeters/Product-Manager-Skills
Writes user stories in Mike Cohn's format with Gherkin acceptance criteria, turning user needs into development-ready work with testable conditions.
A skill your agent uses when building any feature, API, module, or system before writing implementation code - produces a structured behavior specification defining inputs, outputs, constraints…
Install Specification First
$ npx skills add NoobyGains/godmode --skill specification-first -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install NoobyGains/godmode specification-first --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/NoobyGains/godmode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/specification-first .claude/skills/specification-first && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "specification-first" agent skill from https://github.com/NoobyGains/godmode/tree/master/skills/specification-first into .claude/skills/specification-first/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "specification-first", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/NoobyGains/godmode/tree/master/skills/specification-firstType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add NoobyGains/godmode --skill specification-first -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install NoobyGains/godmode specification-first --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/NoobyGains/godmode.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/specification-first .agents/skills/specification-first && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "specification-first" agent skill from https://github.com/NoobyGains/godmode/tree/master/skills/specification-first into .agents/skills/specification-first/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "specification-first", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add NoobyGains/godmode --skill specification-first -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install NoobyGains/godmode specification-first --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/NoobyGains/godmode.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/specification-first .cursor/skills/specification-first && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "specification-first" agent skill from https://github.com/NoobyGains/godmode/tree/master/skills/specification-first into .cursor/skills/specification-first/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "specification-first", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/NoobyGains/godmode.git --path skills/specification-first--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add NoobyGains/godmode --skill specification-first -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install NoobyGains/godmode specification-first --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/NoobyGains/godmode.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/specification-first .gemini/skills/specification-first && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "specification-first" agent skill from https://github.com/NoobyGains/godmode/tree/master/skills/specification-first into .gemini/skills/specification-first/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "specification-first", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install NoobyGains/godmode specification-firstInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add NoobyGains/godmode --skill specification-first -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/NoobyGains/godmode.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/specification-first .github/skills/specification-first && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "specification-first" agent skill from https://github.com/NoobyGains/godmode/tree/master/skills/specification-first into .github/skills/specification-first/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "specification-first", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add NoobyGains/godmode --skill specification-first -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install NoobyGains/godmode specification-first --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/NoobyGains/godmode.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/specification-first .opencode/skills/specification-first && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "specification-first" agent skill from https://github.com/NoobyGains/godmode/tree/master/skills/specification-first into .opencode/skills/specification-first/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "specification-first", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
specification-first- GitHub stars
- 107
- Token cost
- ~1.7k tokens
- SKILL.md length
- 502 words
- Files
- 1
- Skills in repo
- 34
- Repo updated
- First seen
- Licence
- MIT
At a glance
A skill your agent uses when building any feature, API, module, or system before writing implementation code - produces a structured behavior specification defining inputs, outputs, constraints…
- Building any feature
- SKILL.md covers Overview, The Prime Directive, When to Use and The Entry Protocol, plus 6 more sections
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
- System before writing implementation code - produces a structured behavior specification defining inputs
What it does
Specification First is an agent skill from NoobyGains/godmode. Use when building any feature, API, module, or system before writing implementation code - produces a structured behavior specification defining inputs, outputs, constraints, edge cases, and acceptance criteria as the authoritative artifact
Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Product & Project Management, covering User stories. The repository describes itself as: The AI development framework that thinks before it builds. 36 composable skills for Claude Code, Cursor, Codex, and OpenCode. The licence is MIT.
When your agent uses it
- Building any feature
- System before writing implementation code - produces a structured behavior specification defining inputs
- Acceptance criteria as the authoritative artifact
Example prompts
- “/specification-first”
What it can do on your machine
Read from SKILL.md and the folder at commit 441103a. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown and dot).
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Specification First loads about 1.7k tokens when it runs. Until then it costs about 65 tokens; SKILL.md has 502 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from NoobyGains/godmode at commit 441103a, republished under its MIT licence (© NoobyGains). 502 words, ~1,677 tokens.
Download SKILL.mdSave it as
.claude/skills/specification-first/SKILL.md (or your agent's skills folder).- name
- specification-first
- description
- Use when building any feature, API, module, or system before writing implementation code - produces a structured behavior specification defining inputs, outputs, constraints, edge cases, and acceptance criteria as the authoritative artifact
Specification First
Overview
Author the specification before the implementation. The specification is the source of truth. Code is generated to satisfy the specification, never the reverse.
Core principle: A behavior specification defines WHAT the system does. Code implements HOW. Without a specification, you are guessing.
No exceptions. No workarounds. No shortcuts.
The Prime Directive
NO IMPLEMENTATION WITHOUT A SPECIFICATION FIRSTIf you have not produced a specification defining inputs, outputs, edge cases, and acceptance criteria, you are not authorized to write code. This is not optional. This is not excessive. This prevents the leading cause of AI-generated code failures: building the wrong thing.
When to Use
Mandatory when:
- Developing a new feature or module
- Creating an API endpoint
- Constructing a data pipeline
- Building any system with defined inputs and outputs
- The user says "build me X" or "create Y"
Exceptions (confirm with the human):
- Configuration changes
- Single-line defect fixes with unambiguous behavior
- Documentation updates
The Entry Protocol
BEFORE writing any implementation code:
1. IDENTIFY: What are the inputs?
2. DEFINE: What are the expected outputs?
3. CONSTRAIN: What are the boundaries and limitations?
4. EDGE: What happens at the edges? (empty, null, maximum, concurrent)
5. ACCEPT: What criteria demonstrate correctness?
6. WRITE: Produce the specification document
7. APPROVE: Obtain user confirmation
8. ONLY THEN: Implement
Omit any step = building the wrong thingSpecification Document Template
# [Feature Name] Specification
## Purpose
[Single sentence: what this does and why it exists]
## Inputs
| Input | Type | Required | Constraints | Default |
|-------|------|----------|-------------|---------|
| [name] | [type] | [yes/no] | [validation rules] | [default] |
## Outputs
| Scenario | Output | Shape |
|----------|--------|-------|
| Success | [what is returned] | [type/structure] |
| Invalid input | [error response] | [error shape] |
| Not found | [404 response] | [error shape] |
## Behavior
### Standard Path
1. [Step-by-step behavior for normal usage]
2. [Include state mutations, side effects]
### Edge Cases
| Case | Input | Expected Behavior |
|------|-------|-------------------|
| Empty input | "" | Return validation error |
| Maximum length | 10000 chars | Truncate to 5000 |
| Concurrent access | 2 simultaneous requests | Serialize second request |
| [case] | [input] | [behavior] |
## Acceptance Criteria
- [ ] [Criterion 1 - testable, specific]
- [ ] [Criterion 2 - testable, specific]
- [ ] [Criterion 3 - testable, specific]
## Explicitly Excluded (YAGNI)
- [Feature intentionally omitted]
- [Optimization intentionally deferred]Relationship with Test-First Development
digraph spec_test_flow {
rankdir=LR;
spec [label="Author Spec\n(this skill)", shape=box style=filled fillcolor=lightyellow];
test [label="Write Failing Test\nfrom Spec Criteria", shape=box style=filled fillcolor="#ffcccc"];
code [label="Write Minimal Code\nto Pass Test", shape=box style=filled fillcolor="#ccffcc"];
verify [label="Verify Against\nSpec Criteria", shape=box style=filled fillcolor="#ccccff"];
spec -> test [label="acceptance criteria\nbecome test cases"];
test -> code [label="test-first cycle"];
code -> verify [label="all criteria satisfied?"];
verify -> spec [label="no - revise spec\nor implementation"];
}Specification -> Tests -> Code -> Verify against Specification
The specification's acceptance criteria map directly to test cases. Each criterion generates at least one test. If you cannot derive a test from a criterion, the criterion is too vague -- refine the specification.
Specification Depth Levels
| Level | When Appropriate | Scope |
|---|---|---|
| Minimal | Simple feature, obvious behavior | Purpose + Inputs + Outputs + 3 acceptance criteria |
| Standard | Most features | Full template above |
| Exhaustive | Complex systems, public APIs, multi-tenant | Full template + sequence diagrams + state machines + error taxonomy |
Scale the specification to the complexity. A utility function warrants a minimal spec. An authentication system demands an exhaustive one.
Show full SKILL.md (247 more words)Show less
Cognitive Traps
| Rationalization | Truth |
|---|---|
| "It is too simple to specify" | Simple features harbor hidden edge cases. A specification takes 2 minutes. |
| "I will figure it out while coding" | You will build the wrong thing and refactor three times. |
| "The user already described what they want" | Users describe goals, not behavior. The specification bridges that gap. |
| "Test-first is sufficient; I do not need a spec" | Test-first tells you WHAT to verify. The specification tells you WHAT to build. Both are necessary. |
| "Specifications slow me down" | Specifications prevent building the wrong thing. That is faster in every measurable way. |
| "I will write the spec afterward" | Specifications written after implementation rationalize what was built, not what should have been built. |
| "AI understands my intent" | AI produces plausible code that may diverge from intent. The specification eliminates ambiguity. |
Guardrails
Prohibited actions:
- Starting implementation before specification approval
- Writing tests without referencing specification criteria
- Changing behavior without updating the specification
- Shipping without verifying against acceptance criteria
- Deferring edge cases ("we will handle those later")
- Writing a specification after implementation is complete
Required actions:
- Obtain specification approval before writing code
- Map acceptance criteria to test cases one-to-one
- Update the specification when requirements evolve
- Verify all criteria pass before declaring completion
- Include explicitly excluded features (what you are NOT building)
Integration
Workflow sequence:
- godmode:intent-discovery -> produces design
- godmode:specification-first -> produces specification from design
- godmode:task-planning -> produces implementation plan from specification
- godmode:test-first -> produces tests from specification criteria
- godmode:completion-gate -> verifies against specification criteria
REQUIRED COMPANION SKILL: Invoke godmode:test-first when implementing
© NoobyGains, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in skills/specification-first of NoobyGains/godmode.
Open the folder on GitHubat commit 441103a
Compare with similar skills
Specification First next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Specification First this skillNoobyGains/godmode | 107 | — | ~1.7k | Automated safety check: Pass | MIT | |
| User Story Writerdeanpeters/Product-Manager-Skills | 7.2k | 2 repos | ~2.9k | Automated safety check: Pass | Custom licence | |
| Ralph Tui Create Beadssubsy/ralph-tui | 2.5k | 1 repos | ~2.6k | Automated safety check: Pass | MIT | |
| Agile Product Owneralirezarezvani/claude-skills | 28k | 3 repos | ~3.2k | Automated safety check: Pass | MIT | |
| Ralph Tui Create Beads Rustsubsy/ralph-tui | 2.5k | 1 repos | ~2.8k | Automated safety check: Pass | MIT | |
| Ralph Tui Create JSONsubsy/ralph-tui | 2.5k | 1 repos | ~2.6k | Automated safety check: Pass | MIT |
Similar skills
Ralph Tui Create Beads
subsy/ralph-tui
Convert PRDs to beads for ralph-tui execution. An agent skill from subsy/ralph-tui.
Agile Product Owner
alirezarezvani/claude-skills
Writes INVEST-checked user stories with acceptance criteria, splits epics, plans sprints from velocity and ranks the backlog with a weighted score.
Ralph Tui Create Beads Rust
subsy/ralph-tui
Convert PRDs to beads for ralph-tui execution using beads-rust (br CLI).
Ralph Tui Create JSON
subsy/ralph-tui
Convert PRDs to prd.json format for ralph-tui execution. An agent skill from subsy/ralph-tui.
Check
VibiumDev/vibium
Independently check application acceptance criteria in a live browser or saved recording with the Vibium CLI.
More from NoobyGains/godmode
All 34 skills in this repoActivation
NoobyGains/godmode
A skill your agent uses when starting any conversation - establishes how to locate and invoke skills, mandating Skill tool usage before ANY response including clarifying questions
Agent Messaging
NoobyGains/godmode
A skill your agent uses when dispatching subagents, composing prompts for teammates, structuring handoff reports, or managing context boundaries between agents.
Codebase Research
NoobyGains/godmode
A skill your agent uses when building ANY feature within an existing project - search the current codebase for existing patterns, conventions, similar implementations, and established approaches…
Completion Gate
NoobyGains/godmode
A skill your agent uses when about to declare work done, fixed, or passing, before committing or opening PRs - demands executing verification commands and reading their output before making any…
Comprehension Check
NoobyGains/godmode
A skill your agent uses when implementing any substantial feature, multi-file modification, or architectural change - produces a plain-language walkthrough of every alteration so the developer can…
Delegated Execution
NoobyGains/godmode
A skill your agent uses when executing implementation plans with independent tasks in the current session
Related
Categories
Questions about Specification First
What does Specification First do?
A skill your agent uses when building any feature, API, module, or system before writing implementation code - produces a structured behavior specification defining inputs, outputs, constraints…. Specification First is an agent skill from NoobyGains/godmode.
When should I use Specification First?
Specification First fits situations like: building any feature; system before writing implementation code - produces a structured behavior specification defining inputs; acceptance criteria as the authoritative artifact.
How do I install Specification First in Claude Code?
Run `npx skills add NoobyGains/godmode --skill specification-first -a claude-code`. Or copy the skill folder (skills/specification-first in NoobyGains/godmode) into .claude/skills/specification-first in your project. Claude Code loads it when a task matches its description.
How do I install Specification First in Codex?
Run `npx skills add NoobyGains/godmode --skill specification-first -a codex`. Or copy the skill folder (skills/specification-first in NoobyGains/godmode) into .agents/skills/specification-first in your project. Codex loads it when a task matches its description.
Can I use Specification First in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add NoobyGains/godmode --skill specification-first -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/specification-first, .gemini/skills/specification-first, .github/skills/specification-first and .opencode/skills/specification-first in your project.
What does Specification First need to run?
SKILL.md names no scripts, command-line tools or credentials: Specification First is instructions for the agent only.
Does Specification First access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Specification First safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Specification First use?
Specification First is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Specification First use?
About 1.7k tokens (SKILL.md is roughly 6.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Specification First?
Skills that share tags, products or a category with Specification First: User Story Writer (deanpeters/Product-Manager-Skills, 7.2k stars), Ralph Tui Create Beads (subsy/ralph-tui, 2.5k stars), Agile Product Owner (alirezarezvani/claude-skills, 28k stars) and Ralph Tui Create Beads Rust (subsy/ralph-tui, 2.5k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Specification First?
NoobyGains (a GitHub user) maintains it in NoobyGains/godmode, which has 107 GitHub stars. The repository holds 34 skills in this directory. The repository was last updated on March 9, 2026.
Source: NoobyGains/godmode on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.