specsfy-aux-database — Claude Code skill: keep a data map
Maintains .specsfy/DATABASE.md with tables of databases, schemas, fields, relations and migrations so the data map matches the code.
npx skills add promovaweb/specsfy --skill specsfy-aux-database -a claude-codeWhat specsfy-aux-database does
The skill walks schemas, migrations, persistent models and configs, then writes a tabular inventory into .specsfy/DATABASE.md. Markdown tables are there for a reason: they are easy to search and diff. Relations, indexes, constraints, ownership, retention and purpose that cannot be inferred safely get flagged as unknown instead of guessed.
Load $specsfy-setup at the project root first and stop if it reports an open item. The skill then reads local instructions, PROJECT.md, STACK.md and the whole DATABASE.md, runs node scripts/update_database.mjs --project <raiz> and checks the detected inventory against executable sources. Anything outside the specsfy:database block stays untouched, so your notes and decisions survive the update.
It runs without asking questions: missing details become a marker for the next step rather than a prompt. A schema change counts as unfinished until DATABASE.md reflects the new structure and the relevant tests pass. Connection strings, passwords, tokens and .env values never make it into the file, which matters when the docs live in a shared repository.
What it helps with
- build a tabular inventory of databases, schemas and fields from code
- check whether the data map still matches current migrations
- flag relations, indexes and constraints that cannot be inferred
- refresh
DATABASE.mdwithout wiping team notes and decisions - treat a schema change as done only after tests pass
Example prompts for the agent
- update the data map in
.specsfy/DATABASE.md - check the database inventory against the current migrations
- I added a table and a migration — refresh the persistence docs
How to install specsfy-aux-database
1Skills CLI (Vercel)
npx skills add promovaweb/specsfy --skill specsfy-aux-database -a claude-code2Manually: put the files in place
~/.claude/skills/specsfy-aux-database/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/specsfy-aux-database/
1Skills CLI (Vercel)
npx skills add promovaweb/specsfy --skill specsfy-aux-database -a codex2Manually: put the files in place
.agents/skills/specsfy-aux-database/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add promovaweb/specsfy --skill specsfy-aux-database -a cursor2Manually: put the files in place
.cursor/skills/specsfy-aux-database/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install promovaweb/specsfy specsfy-aux-database2Manually: put the files in place
.github/skills/specsfy-aux-database/SKILL.md1Skills CLI (Vercel)
npx skills add promovaweb/specsfy --skill specsfy-aux-database -a gemini-cli2Platform CLI
gemini skills install https://github.com/promovaweb/specsfy --path skills/specsfy-aux-databaseManually: put the files in place
.devin/skills/specsfy-aux-database/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add promovaweb/specsfy --skill specsfy-aux-database -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 specsfy-aux-database
How do I install specsfy-aux-database in Claude?
Run npx skills add promovaweb/specsfy --skill specsfy-aux-database -a claude-code. The skill lands in ~/.claude/skills/specsfy-aux-database/SKILL.md.
What does specsfy-aux-database do?
It builds and maintains .specsfy/DATABASE.md: tables of databases, schemas, tables, fields, relations and migrations, verified against the code.
What has to happen before the skill runs?
$specsfy-setup must be loaded at the project root with no open item. On automatic handoff the skill loads it again before this step.
