Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add siviter-xyz/dot-agent --skill psi -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/psi/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/psi/

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

Similar skills

SKILL.md skills catalog →

From the same set11

The whole set →
software-engineer software-engineer — a skill that gives the agent rules for code style, documentation and workflow: no filler comments, no git commits on its own, questions when something is unclear. CX Codex +1 637installs python Gives the agent one set of Python conventions: typing, dependency injection, module and test layout. Useful when edits land in an existing codebase. CX Codex +1 353installs create-agents-md create-agents-md generates repo-committed AGENTS.md files for inline rules. Useful for keeping code style, build commands, and safety boundaries close to the code. CX Codex +1 306installs typescript typescript is a Claude Code skill that sets standards for writing and changing TypeScript. It activates for TypeScript and TypeScript React files. CX Codex +1 239installs cli-building cli-building guides AI agents to build command-line tools using async-first patterns, modular command composition, and terminal formatting with NO_COLOR support. CX Codex +1 201installs semantic-git The semantic-git skill groups related changes into atomic commits and formats messages as Conventional Commits. Use it when an agent is preparing Git changes for commit. CX Codex +1 201installs debugging debugging is a Claude Code skill that guides root cause analysis for errors and test failures. It helps localize bugs and prepare minimal, verified fixes. CX Codex +1 151installs media-processing media-processing is a Claude Code skill for batch media workflows: resizing images, converting audio, and compressing video with FFmpeg, ImageMagick, and Python scripts. CX Codex +1 151installs

Project sponsors

Companies that keep this analytics open