psi — Claude Code skill: workflow and installation
psi structures development around planning, specifications and test-first implementation. It runs only when the user asks for it or the project’s AGENTS.md mentions it.
MIT 144 installs ★ 22 updated 2026-03-21
npx skills add siviter-xyz/dot-agent --skill psi -a claude-codeWhat psi does
psi splits work into Plan, Spec and Implement phases. Plans and research go under ~/.dot-agent/, while specifications are applied to docs/, README.md files and AGENTS.md. You can begin with any phase, but each one keeps project documentation current.
During implementation, the workflow calls for tests covering docs and user journeys before code changes. It also checks types, tests and lint before commits, groups related work into atomic commits, and updates docs as the code changes. psi does not run on its own; the user must request it or the project’s AGENTS.md must mention the skill.
What it helps with
- keep a work plan and research outside the repository
- document API schemas, data models and user journeys
- write documentation and user-journey tests before changing code
- check types, tests and lint before committing
Example prompts for the agent
- Use the psi skill to plan an export feature for this project.
- Run psi's Spec phase and document the new API.
- Use psi's Implement phase: add tests first, then make the code changes.
How to install psi
1Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill psi -a claude-code2Manually: put the files in place
~/.claude/skills/psi/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/psi/
1Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill psi -a codex2Manually: put the files in place
.agents/skills/psi/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill psi -a cursor2Manually: put the files in place
.cursor/skills/psi/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install siviter-xyz/dot-agent skills/psi2Manually: put the files in place
.github/skills/psi/SKILL.md1Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill psi -a gemini-cli2Platform CLI
gemini skills install https://github.com/siviter-xyz/dot-agent --path skills/psiManually: put the files in place
.devin/skills/psi/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill psi -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 psi
How do I install psi in Claude Code?
Run npx skills add siviter-xyz/dot-agent --skill psi -a claude-code. The skill file is installed at ~/.claude/skills/psi/SKILL.md.
What does the psi skill do?
It guides development through Plan, Spec and Implement phases. Plans stay under ~/.dot-agent/, specifications are added to project documentation, and implementation starts with tests.
Does psi run automatically?
No. Use it when the user explicitly requests it or when the project’s AGENTS.md mentions the skill.
Source text
SKILL.md · MIT
--- name: psi description: Plan-spec-implement workflow for structured development. Only use when explicitly directed by user or when mentioned in project AGENTS.md file. Generates ephemeral plans in ~/.dot-agent/, applies specs to project docs, then implements test-first. license: MIT --- # PSI - Plan Spec Implement Structured workflow for planning, specifying, and implementing changes with documentation-first approach. ## When to Use **Only use when:** - Explicitly directed by the user - Mentioned in project `AGENTS.md` file **Do not use automatically** - this is an opt-in workflow, not a default. ## Core Workflow **Plan → Spec → Implement** Phases are **independent** - you can start with any phase, but all must ensure documentation stays up-to-date. ## Key Principles 1. **Ephemeral planning** - Plans stored in `~/.dot-agent/` (not committed) 2. **Documentation-first** - Specs applied to project docs/READMEs/AGENTS.md 3. **Test-first implementation** - Tests for docs/user journeys before code 4. **Design/review embedded** - Design and review integrated into Plan/Spec phases 5. **Phase independence** - Each phase can work standalone, all update docs ## Phase Overview ### Plan Phase - Generates detailed plans in `~/.dot-agent/repo/YYYY-MM-work-name.plan.md` - Research stored in `~/.dot-agent/working-dir/repo/YYYY-MM-work-name.research.md` - Embeds design considerations - Includes review before proceeding ### Spec Phase - Generates specs for: API schemas, interfaces, DTOs, database models, config, env vars, architecture, user journeys, package structure, tech choices - Embeds design considerations - Reviews specs before applying - Applies to: `docs/`, README.md files, AGENTS.md files ### Implement Phase - Test-first: tests for docs/user journeys before code - CI verification: verify types, tests, lint pass before committing - Atomic commits: group related changes with tests - Updates docs, README.md, AGENTS.md as code evolves - Can work independently if specs exist in docs ## Research Management Detects phrases like: - "looking at your research" → Loads research file - "refine your research" → Updates research file, narrows focus ## Documentation Structure - **README.md**: Aim for < 1000 lines (not hard rule), can be longer if needed - **AGENTS.md**: < 200 lines, inline at root/packages/modules/code level - **docs/**: Architecture, roadmap, tech-choices, setup/, user-journeys/, design/ ## References For detailed protocols, see: - `references/plan-phase.md` - Plan generation with embedded design/review - `references/spec-phase.md` - Spec generation and application - `references/implement-phase.md` - Test-first implementation - `references/review-protocol.md` - Reviewing plans/specs/design - `references/research-management.md` - Research file handling - `references/docs-structure.md` - Documentation organization rules - `references/file-paths.md` - Storage paths and conventions
© siviter-xyz · MIT · siviter-xyz/dot-agent