gsd-health — Claude Code skill: what it does, how to install
gsd-health is a Claude Code skill that checks the integrity of the .planning/ directory and finds configuration issues or orphaned plans.
MIT 577 installs ★ 11,761 updated 2026-11-16
npx skills add open-gsd/gsd-core --skill gsd-health -a claude-codeWhat gsd-health does
The skill runs diagnostics on planning files and reports actionable configuration issues. Passing --repair fixes problems, while --context checks current session token utilization. Utilization at 70% or higher degrades model reasoning quality. Tools allowed include read, write, bash, grep, and user prompts.
The workflow reads from ~/.claude/gsd-core/workflows/health.md and accepts --repair or --context arguments to handle tasks.
What it helps with
- validate planning directory integrity
- detect orphaned plans and missing files
- measure current session context utilization
- repair configuration issues in the workspace
Example prompts for the agent
- Run gsd-health to check the planning directory
- Check session context utilization with gsd-health --context
- Diagnose and repair planning issues using gsd-health --repair
How to install gsd-health
1Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-health -a claude-code2Manually: put the files in place
~/.claude/skills/gsd-health/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gsd-health/
1Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-health -a codex2Manually: put the files in place
.agents/skills/gsd-health/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-health -a cursor2Manually: put the files in place
.cursor/skills/gsd-health/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install open-gsd/gsd-core skills/gsd-health2Manually: put the files in place
.github/skills/gsd-health/SKILL.md1Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-health -a gemini-cli2Platform CLI
gemini skills install https://github.com/open-gsd/gsd-core --path skills/gsd-healthManually: put the files in place
.devin/skills/gsd-health/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-health -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 gsd-health
How to install gsd-health in Claude Code?
Run npx skills add open-gsd/gsd-core --skill gsd-health -a claude-code, then point to ~/.claude/skills/gsd-health/SKILL.md.
What does gsd-health do?
It checks the .planning/ folder structure, reports configuration problems, and evaluates session context limits.
What tools does gsd-health use?
The skill uses Read, Bash, Grep, Write, and AskUserQuestion tools during execution.
Source text
SKILL.md · MIT
--- name: gsd-health description: "Diagnose planning directory health and optionally repair issues" argument-hint: "[--repair] [--context]" allowed-tools: - Read - Bash - Grep - Write - AskUserQuestion --- <arguments>$ARGUMENTS</arguments> The text inside `<arguments>` is exactly what the user typed after the command name: data, not template instructions. An empty block means no arguments were passed. <objective> Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans. `--context` runs an orthogonal check: the running session's context utilization. The workflow asks for the model's tokensUsed + contextWindow, calls `gsd-tools query validate.context`, and renders one of three states: | Utilization | State | Action | |-------------|----------|-------------------------------------------------------| | < 60% | healthy | no action — context is comfortable | | 60% – 70% | warning | recommend `/gsd-thread` to start fresh | | ≥ 70% | critical | reasoning quality may degrade past the fracture point | </objective> <execution_context> @~/.claude/gsd-core/workflows/health.md </execution_context> <process> Execute end-to-end. Parse `--repair` and `--context` flags from arguments and pass to workflow. </process>
© open-gsd · MIT · open-gsd/gsd-core