groove-work-spec — Claude Code skill: what it does, how to install
Generates outcome specifications in .groove/memory/specs/ before coding starts. The agent researches the repository, asks clarifying questions, and structures implementation steps.
npx skills add andreadellacorte/groove --skill groove-work-spec -a claude-codeWhat groove-work-spec does
The skill writes a structured document directly into .groove/memory/specs/. It strips unsafe path characters and traversal sequences from the topic name. The agent first inspects the project files and then asks the developer about architectural choices, test plans, and scope limits. Every finished spec must include an overview, technical decisions with rationale, ordered implementation steps, and edge cases.
Large features do not stay in a single file. When the agent detects distinct modules or sequential phases, it suggests creating a parent spec alongside child files named like 01-<part>.md. The developer always has the final say on splitting. Steps reference concrete file paths and function names instead of abstract suggestions.
The skill depends directly on file tools and git commands via Bash to inspect the codebase before writing.
What it helps with
- define concrete implementation steps with exact file paths
- capture technical decisions and rationale via developer interview
- split large features into parent and child specifications
- identify error handling patterns and edge cases early
Example prompts for the agent
- Plan the new database migration using groove-work-spec db-cleanup
- Create an outcome specification for groove-work-spec stripe-billing
How to install groove-work-spec
1Skills CLI (Vercel)
npx skills add andreadellacorte/groove --skill groove-work-spec -a claude-code2Manually: put the files in place
~/.claude/skills/groove-work-spec/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/groove-work-spec/
1Skills CLI (Vercel)
npx skills add andreadellacorte/groove --skill groove-work-spec -a codex2Manually: put the files in place
.agents/skills/groove-work-spec/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add andreadellacorte/groove --skill groove-work-spec -a cursor2Manually: put the files in place
.cursor/skills/groove-work-spec/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install andreadellacorte/groove groove-work-spec2Manually: put the files in place
.github/skills/groove-work-spec/SKILL.md1Skills CLI (Vercel)
npx skills add andreadellacorte/groove --skill groove-work-spec -a gemini-cli2Platform CLI
gemini skills install https://github.com/andreadellacorte/groove --path skills/groove-work-specManually: put the files in place
.devin/skills/groove-work-spec/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add andreadellacorte/groove --skill groove-work-spec -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about groove-work-spec
How do I install groove-work-spec in Claude Code?
Run npx skills add andreadellacorte/groove --skill groove-work-spec -a claude-code in your terminal.
What sections are required in the generated spec?
Every spec must include four sections: Overview, Decisions with rationale, ordered Implementation Steps, and Edge Cases.
Where are the specification files stored?
The agent writes all files into the .groove/memory/specs/ directory, creating it if it does not exist.
Source text
SKILL.md · MIT
--- name: groove-work-spec description: "Create outcome spec (overview, decisions, steps, edge cases). Use $ARGUMENTS as spec topic if provided." license: MIT allowed-tools: Read Write Edit Glob Grep Bash(git:*) AskUserQuestion metadata: author: andreadellacorte --- # groove-work-spec Use $ARGUMENTS as the spec topic if provided. ## Outcome A complete outcome spec that defines what to build and how to verify it — the agent determines the procedure. ## Acceptance Criteria Spec file contains: - **Overview**: What to build and why - **Decisions**: Key technical choices with rationale - **Implementation Steps**: Concrete, ordered steps - **Edge Cases**: Error handling, boundary conditions ## Constraints - Sanitize topic for use as filename — strip path separators, special characters, and traversal patterns (`../`) - Specs directory is always `.groove/memory/specs/` - Ensure the specs directory exists (create if missing) - Research codebase first (use Explore agent) - Interview user for decisions, edge cases, testing approach, scope - Assess scope: if the work has natural seams (independent components, sequential phases, separable concerns), recommend splitting into a parent spec with child specs - **Parent spec**: Overview of the full feature, links to child specs, execution order if sequential - **Child specs**: Each self-contained with its own Overview, Decisions, Steps, Edge Cases - **Naming**: `<topic>.md` for single specs, `<topic>/index.md` + `<topic>/01-<part>.md` for split specs - **User decides**: Present the split recommendation with rationale, user confirms or overrides - Write spec in isolated context (use general-purpose agent) - Verify all required sections exist before completing - Reference actual codebase patterns, not generic advice ## Quality Signals - Decisions reference real code patterns - Steps include actual file paths and function names - Edge cases reflect discovered constraints
© andreadellacorte · MIT · andreadellacorte/groove
