momentic-spec — Claude Code skill: specs before code
A skill that makes the agent write Momentic tests before implementing anything, so the tests define the contract instead of matching finished code.
npx skills add momentic-ai/skills --skill momentic-spec -a claude-codeWhat momentic-spec does
The skill enforces a fixed order. The agent reads momentic.config.yaml, nearby tests and modules, names the exact Momentic tests the change will touch, and only then creates or edits them. Product code comes after the specs are on disk. If the requirement shifts, the spec is updated first.
Picking the affected set has its own rules. New user-visible behavior gets the smallest new test that describes the journey; changed behavior means updating the existing test rather than adding duplicate coverage. Shared modules are touched only when the requested contract requires it, and every test consuming them is accounted for. A weak assertion does not survive just because it matches what the code does today.
Momentic is end-to-end validation here, not the agent's inner loop. It does not run after every edit or commit. Unit tests, typechecking and linting carry the build; before a long run the agent states which tests it proposes and the expected duration, then waits for confirmation. A test gets disabled: true when the implementation or a dependency is not ready, with a note on what must change before enabling it. Missing local credentials are not a reason to disable it.
What it helps with
- write the expected behavior as a test before coding it
- find every Momentic test a change will affect
- update an existing test instead of duplicating coverage
- check a shared module and all tests that consume it
- hold end-to-end runs until a durable checkpoint
Example prompts for the agent
- add the password reset flow: spec it in Momentic first, then implement
- which Momentic tests does the auth module change affect?
- update the old checkout test instead of adding a new one
How to install momentic-spec
1Skills CLI (Vercel)
npx skills add momentic-ai/skills --skill momentic-spec -a claude-code2Manually: put the files in place
~/.claude/skills/momentic-spec/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/momentic-spec/
1Skills CLI (Vercel)
npx skills add momentic-ai/skills --skill momentic-spec -a codex2Manually: put the files in place
.agents/skills/momentic-spec/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add momentic-ai/skills --skill momentic-spec -a cursor2Manually: put the files in place
.cursor/skills/momentic-spec/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install momentic-ai/skills momentic-spec2Manually: put the files in place
.github/skills/momentic-spec/SKILL.md1Skills CLI (Vercel)
npx skills add momentic-ai/skills --skill momentic-spec -a gemini-cli2Platform CLI
gemini skills install https://github.com/momentic-ai/skills --path skills/momentic-specManually: put the files in place
.devin/skills/momentic-spec/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add momentic-ai/skills --skill momentic-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 momentic-spec
How do I install momentic-spec in Claude?
Run npx skills add momentic-ai/skills --skill momentic-spec -a claude-code. The skill lands at ~/.claude/skills/momentic-spec/SKILL.md.
What does momentic-spec do?
It makes the agent write or modify Momentic tests before touching product code. The tests act as the specification and are not weakened to fit the current implementation.
When does the skill run Momentic tests?
At a durable checkpoint, not after every edit or commit. Before a long run the agent names the tests and expected duration and asks for confirmation.
