Skip to content

About

a skills.sh agent skill for writing specs as a linked, ADR-driven knowledge base. Obsidian-first, works in plain Markdown.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

39 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 

Repository files navigation

The spec lives next to the code

A method (and an agent skill) for keeping a software spec beside the code it describes. The code says what the product does. The spec says why, and what we chose not to do.

What Where it lives
A reason for one place in the code A comment at that place
A number A named constant, with its reason in a comment
A rule that spans several files of one part The CLAUDE.md of the package that owns the part
What the product is, for whom, its main paths A short product spec for people, in docs/spec
A bug, a plan, an open question An issue

A CLAUDE.md holds only three kinds of text: a rule that spans several files, a rejected way, and a rule of absence. It never retells the code. One fact lives in one file, and a comment points at it by heading or by symbol.

Why not a vault of linked notes

Earlier versions of this skill described a spec as a vault of small linked notes. In practice such a vault retold the code, and a large share of it went stale. Its notes pointed at each other in long chains, and an agent spent its context on them. A CLAUDE.md in the package folder reaches the agent by itself: Claude Code loads it when it works in that folder.

The old vault method and its check scripts are in the git history of this repo.

What's in here

skills/spec-rules/
  SKILL.md                          The method, as an agent skill

Use as an agent skill

Install with the skills.sh CLI (works with Claude Code, Codex, Cursor, OpenCode, and others):

npx skills add sedlukha/spec-rules

This installs skills/spec-rules/. Or copy that folder by hand into your skills directory, for example .claude/skills/spec-rules/.

The model can start the skill on its own, when the work looks like spec writing. To make it explicit only, add disable-model-invocation: true to the frontmatter. Then it runs when you call it by name, and never on its own.

About

a skills.sh agent skill for writing specs as a linked, ADR-driven knowledge base. Obsidian-first, works in plain Markdown.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors