feat(pi): add skills and improve AGENTS.md reading guidelines

- Add 'create-skill' skill for scaffolding new skill directories
- Add 'planning' skill for structured implementation workflows
- Add search-then-read pattern guidance to AGENTS.md

modules/home/programs/terminal/pi/config/AGENTS.md

@@ -34,6 +34,23 @@ bash(command="cat > file.txt << 'EOF'\ncontent\nEOF")
 write(path="file.txt", content="content")
 ```
 
+## Reading Files
+
+Prefer a **search → targeted read** pattern to minimize context usage:
+
+1. **Search** with `grep -n` / `rg -n` to find relevant line numbers.
+2. **Read** only the needed range using `read(path, offset, limit)` or `sed -n 'X,Yp'`.
+
+```bash
+# Find the relevant lines
+bash(command="rg -n 'functionName' src/", timeout=10)
+
+# Read just that region (e.g. lines 42-70)
+read(path="src/foo.go", offset=42, limit=29)
+```
+
+Full-file reads are fine when genuinely needed (small files, needing full picture), but avoid them as the default reflex.
+
 ## Principles
 
 1. **KISS / YAGNI** - Keep solutions simple and straightforward. Don't introduce abstractions, generics, or indirection unless there is a concrete, immediate need. Prefer obvious code over clever code.

modules/home/programs/terminal/pi/config/skills/create-skill/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: create-skill
+description: 'Create a new skill in the skills directory. Use when user asks to add a skill, create a skill, or mentions "/create-skill". Produces a SKILL.md with frontmatter and optional helper scripts, following conventions from existing skills.'
+---
+
+# Create Skill
+
+## Overview
+
+Scaffold a new skill directory with a `SKILL.md` and optional helper scripts under the project's skills directory.
+
+## Workflow
+
+### 1. Gather Requirements
+
+Ask the user:
+- **What does the skill do?** (trigger conditions, purpose)
+- **Are there repeatable commands?** (if yes, these become scripts)
+
+If the user already provided enough detail, skip straight to drafting.
+
+### 2. Draft the Skill
+
+Create `skills/<skill-name>/SKILL.md` with this structure:
+
+```markdown
+---
+name: <skill-name>
+description: '<One-liner: what it does and when to trigger. Keep under ~200 chars.>'
+---
+
+# <Skill Title>
+
+## Overview
+[1-2 sentences on purpose and scope]
+
+## Workflow
+[Numbered steps the agent follows]
+```
+
+**Guidelines:**
+- **Be concise.** Skills are injected into agent context — every line costs tokens. Aim for the minimum needed to reliably guide the agent.
+- **Use scripts for repeatable logic.** If a step involves a multi-line shell command, `jq` pipeline, or API call that won't change between runs, put it in a `.sh` file next to `SKILL.md` and reference it from the workflow. See `address-gh-review/` for an example.
+- **Frontmatter is required.** `name` and `description` fields. The description is what the agent uses to decide whether to load the skill, so make it specific about trigger conditions.
+- **Don't over-specify.** Trust the agent to fill gaps. Document the _what_ and _when_, not every micro-step.
+
+### 3. Present for Review
+
+Show the user the draft and wait for approval before finalizing. Apply any requested changes.
+
+### 4. Git Add
+
+Run `git add` on the new skill directory so the flake/tooling can discover it.

modules/home/programs/terminal/pi/config/skills/planning/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: planning
+description: 'Create a structured plan before implementing broad or non-trivial changes. Use when user requests a new feature spanning multiple areas, significant refactoring, or explicitly asks to "plan this out". Produces a plan document in _scratch/, waits for user approval, then tracks progress as tasks are completed.'
+---
+
+# Planning Workflow Skill
+
+## When to Use
+
+Trigger this workflow when:
+- A user requests a **broad or non-trivial change** (e.g. new feature spanning frontend/backend, significant refactoring)
+- A user says things like "plan this out", "create a plan", or "do this properly"
+
+Don't trigger for routine multi-file changes like renames, simple bug fixes, or mechanical refactors.
+
+## Rules
+
+### 1. Always Start with a Plan
+
+**Before touching any code**, create a markdown plan in `_scratch/plan-[short-name].md` with:
+- A clear title and status
+- Clarifications section (if any unknowns)
+- Phased tasks as checkboxes (`- [ ]`)
+
+### 2. Ask Clarifying Questions First
+
+When a requirement is **ambiguous or has multiple valid interpretations**:
+- List your interpretations
+- Ask the user to confirm
+- Document answers in the plan's "Clarifications" section
+
+### 3. Wait for User Approval
+
+Present the plan and wait for the user to confirm before implementing. If the user requests changes, update the plan first.
+
+### 4. Update the Plan as You Work
+
+- Change `- [ ]` to `- [x]` for completed items
+- Note any deviations from the original plan
+- If you discover new tasks, add them with a note explaining why
+
+### 5. Plan Document Format
+
+```markdown
+# Plan: [Feature Name]
+
+> **Status**: ⏳ In Progress | ✅ Complete | ❌ Blocked
+
+## Clarifications
+
+- ~~Question?~~ **Answer**
+
+## Tasks
+
+### Phase 1: [Name]
+- [ ] Task 1
+- [ ] Task 2
+
+### Phase 2: [Name]
+- [ ] Task 3
+
+## Rollback Plan (if destructive/irreversible)
+[How to undo if needed]
+```
+
+## Anti-Patterns
+
+- ❌ Coding before the user approves the plan
+- ❌ Making assumptions about ambiguous requirements
+- ❌ Plans that are too vague ("update code")
+- ❌ Forgetting to update the plan as you work