Setup

/setup

Write a small JSON config that the planning skills consult to find the plans directory and decide whether to manage .gitignore. This skill writes at most two files: .claude/plans-config.json and (optionally) .gitignore.

Asking questions

This skill prefers the AskUserQuestion tool for interactive prompts. If AskUserQuestion is not available (older Claude Code versions, restricted environments), fall back to plain text: print the question, list the options as a numbered list with the recommended option marked (Recommended), and wait for the user's reply (a number or the option label). The skill proceeds normally in either mode — every call site below that says "call AskUserQuestion" follows this fallback rule.

Operating mode

• Two writes max. .claude/plans-config.json and (only if needed) an append to .gitignore. No other writes.
• Read-only on code. This skill does not touch any source file.
• Non-destructive on .gitignore. Never remove or rewrite existing .gitignore lines. Only append when missing.
• Defaults are the historical path. plansDir defaults to .claude/plans; gitignore defaults to true. Users who never run /setup get the same behavior as before.

Config file contract

.claude/plans-config.json:

{
  "plansDir": ".claude/plans",
  "gitignore": true
}

• plansDir: string, relative or absolute path. Default .claude/plans. Absolute paths are allowed (some users keep plans outside the repo).
• gitignore: boolean. If true, skills ensure plansDir is in .gitignore. If false, skills do not touch .gitignore.

Phases

Phase 1 — Detect existing config

Read .claude/plans-config.json if it exists. If present:

1. Show the current values.
2. Ask via AskUserQuestion: "Config already exists. Reconfigure or keep as-is?" with options "Keep" (Recommended) and "Reconfigure".
3. If "Keep", end the turn after printing the current config.
4. If "Reconfigure", proceed to Phase 2.

If .claude/plans-config.json does not exist, proceed to Phase 2.

Phase 2 — Q&A

Ask two questions via AskUserQuestion, one at a time, recommended-answer option first.

1. Plans directory. Options: .claude/plans (Recommended), Other (user types a path). Accept absolute or relative paths.
2. Gitignore the plans directory? Options: Yes (Recommended), No.

Phase 3 — Write config

1. Create .claude/ if it does not exist.
2. Write .claude/plans-config.json with the chosen plansDir and gitignore values.
3. If gitignore: true:

• If a .gitignore exists at the project root and does not already contain a line matching plansDir (with optional trailing /), append / to it.
• If .gitignore does not exist, create it with that single line.

1. If gitignore: false:

• Do not modify .gitignore.
• If .gitignore exists and already contains a line matching plansDir, print a note: "Your .gitignore still contains ``. Remove it manually if you want plans tracked in git."

Phase 4 — Confirm

Print a summary:

✅ Config written: .claude/plans-config.json
   plansDir: 
   gitignore: 

End the turn.

Constraints

• Never write outside .claude/plans-config.json and .gitignore.
• Never remove existing .gitignore lines.
• Defaults must match the historical behavior (.claude/plans, gitignored).
• Ask questions via AskUserQuestion; one question at a time; recommended-answer option first.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vpaivag
• Source: vpaivag/skills
• License: MIT

Install and usage instructions live in the source repository linked above.