Skip to content

CUSTOMIZE.md

Latest commit

 

History

History
295 lines (181 loc) · 8.77 KB

CUSTOMIZE.md

File metadata and controls

295 lines (181 loc) · 8.77 KB
Raw

CUSTOMIZE — write your own slash commands and agents

Read after USAGE.md. This is how you extend the Personal OS for your workflow without breaking the architecture.

The system ships with ~25 slash commands and ~11 subagents. They cover the universal layer + your archetype pack. As you use the system, you'll find friction points the defaults don't cover — that's the signal to add your own.

Don't customize prematurely. Use the defaults for at least 30 days first. The Activation Gate (docs/activation-gate.md) exists because customers who customize before they've internalized the rituals tend to build commands they then abandon.

When to add a custom command

You're ready to add one when:

  1. You've done the same multi-step workflow manually 3+ times
  2. The workflow is bounded (specific input → specific output)
  3. The workflow is reusable (you'll do it weekly+, not once)
  4. No existing command does it (check .claude/commands/_README.md first)

Don't add a command for:

  • One-off workflows
  • Things you do once a quarter
  • Decisions that should stay deliberate (don't automate judgment calls)
  • Things that already exist (/draft, /capture, /scratch are deliberately broad)

Anatomy of a slash command

Open any file in .claude/commands/ to see the pattern. Example: .claude/commands/morning-journal.md.

Each command is a single markdown file with:

---
description: One-line description shown in Claude Code's command list
---

User invoked `/your-command <args>`. Do this:

1. Step 1 — what to read
2. Step 2 — what to ask the user
3. Step 3 — what to write

**Output format:**

[Specify exactly what gets written, where, with what frontmatter]

**Hard rules:**

- Don't fabricate
- Don't auto-promote
- [your own rules]

**Different from:**

- `/similar-command` — explain the difference

The filename (without .md) is the slash command name. morning-journal.md → /morning-journal.

Your first custom command — the 5-step recipe

Step 1 — Name it

Verb-noun, lowercase, hyphenated. /weekly-roi-check not /check.

Step 2 — Define the IPO (input → process → output)

Write three lines before you write anything else:

  • Input: what the user types after the slash
  • Process: what files get read, what reasoning happens
  • Output: what file gets written / updated, with what shape

If you can't write those three lines clearly, you don't have a command yet — you have a vague workflow.

Step 3 — Pick the right routing

If the command does... Route to...
A single file edit Just do the edit (no agent needed)
Cross-pillar synthesis os-synth subagent
Pillar-bounded reasoning The relevant pillar agent
Drafting in your voice content-strategist (or archetype equivalent)
Body-gated decision body-keeper
Money math finance-keeper

Most commands route to one agent. Don't chain multiple agents in v1 — that's premature complexity.

Step 4 — Write the file

Create .claude/commands/your-command.md using the anatomy above.

Two principles to honor:

  • State lives in files — your command should read from canonical files, not hardcode numbers
  • No fabrication — [fill] markers if data is missing; never invent

Step 5 — Test on real input three times

Before you trust it, run it on three real situations. If it fails on any, iterate the prompt. Common failure modes:

  • Too vague — add explicit step numbering
  • Too rigid — let the agent decide the shape based on input
  • Wrong agent — re-route
  • Writes to wrong file — be specific about output path

When to add a custom subagent

Higher bar than commands. Add a subagent when:

  1. You have a persistent specialist concern that spans multiple commands (e.g., "everything book-related" → book-keeper)
  2. The concern has its own context window worth protecting (lots of files to read, lots of state)
  3. You'd benefit from separation of voice / rules / decision logic from the command surface

Most customers never need to write a custom subagent. The 7 universal + archetype-pack agents cover most workflows.

Anatomy of a subagent

Open any file in .claude/agents/ to see the pattern. Example: .claude/agents/content-strategist.md.

---
name: agent-name
description: One-line description used by the routing layer
tools: Read, Grep, Glob, Bash, Write, Edit
---

# agent-name — what this agent does

[2-3 sentence framing]

## Start-of-session ritual

1. Read X
2. Read Y
3. Check Z

## Context every session must hold

- Bullet 1
- Bullet 2

## Hard rules

1. Rule 1
2. Rule 2

## Where you can write

- `path/to/folder/*.md` — what kind of files

## Decision logic

### "When user asks for X"
[steps]

### "When user asks for Y"
[steps]

## Default response shape

1. Step 1
2. Step 2

## Voice

[voice rules — match this customer's voice, not generic Claude]

## Closing

[end-line patterns]

Three patterns to copy

Pattern 1 — the capture command

Reads a one-line input, writes to a canonical file with frontmatter, mirrors a derived line to a content surface. Models: quote.md, win-capture.md, scratch.md.

Use this when: friction-free capture of structured items.

Pattern 2 — the draft command

Reads source material + voice rules, drafts an artifact to drafts/, doesn't auto-publish. Models: draft.md, post-draft.md, partnership-pitch.md.

Use this when: producing a written artifact that needs review before going live.

Pattern 3 — the audit command

Reads multiple files across a pillar, surfaces drift / pending decisions / next 3 actions. Models: pillar-audit.md, stale-sweep.md, tag-audit.md.

Use this when: periodic health-check of a domain.

Customizing the existing agents

Light edits are fine. Heavy edits are risky.

Safe to edit:

  • Voice rules in any agent (match your tone)
  • Hard rules (add your own constraints)
  • Decision logic for new situations you've encountered
  • File paths if you've reorganized

Risky to edit:

  • Tool list in frontmatter (don't grant Bash unrestricted)
  • The "state lives in files" rule (load-bearing)
  • The sacred-file protections (identity/adn.md, identity/personal.md)
  • The os-synth cross-pillar synthesis logic (if you break this, the system loses its glue)

When in doubt, copy the agent to your-version-of-name.md, edit the copy, leave the original intact.

Customizing settings.json

Live at .claude/settings.json. Three things you might tune:

1. Permissions

Default is conservative. Add tool permissions only when you've hit a "permission denied" prompt and confirmed the tool is safe.

"permissions": {
  "allow": [
    "Read", "Glob", "Grep", "Edit", "Write",
    "Bash(git status:*)", "Bash(git log:*)"
  ]
}

2. Autonomous mode hooks

Default OFF. The settings file has three commented examples:

  • Auto-link after morning-journal — recommended if you use /morning-journal daily
  • Session log append — recommended for power users who want continuity
  • Pre-call check gate — only if you're in active recovery from over-extension

Copy the example block from _autonomous_mode_examples into the active hooks section to activate.

Don't enable all three on day one. Start with one. Run for 14 days. Add the next.

3. Per-archetype tools

Creator pack might want Bash(ffmpeg:*) for video work. Founder pack might want Bash(stripe-cli:*) for billing. Add cautiously and document in HANDOFF.md § Customizations.

Versioning your customizations

Once you're committing changes, write commit messages that capture why:

git commit -m "add /weekly-roi-check command — repeated this audit 4x manually"
git commit -m "tighten content-strategist voice rules — too verbose for my style"
git commit -m "add ffmpeg permission — needed for episode-plan video transcoding"

The commit log becomes your customization history. Re-read it during /monthly reviews to see what worked.

When customization signals something else

Sometimes "I need a custom command" is actually:

  • You're avoiding a real decision (don't automate the avoidance)
  • You're optimizing a pillar that should be sunset (a pillar producing zero value should be archived, not optimized)
  • You're scaling complexity instead of capacity (Growth Doctrine #5: one pillar per quarter)

If you're 6+ commands deep into customization in a single month, surface it at your next sync with your operator. The system is meant to compound, not bloat.

What's next

→ HANDOFF.md — what got built specifically for you → docs/support-slas.md — when to message your operator → .claude/commands/_README.md — full manifest of shipped commands → .claude/agents/_README.md — full manifest of shipped agents