docs(pi/agents): expand principles and comment style guidance

Add explicit priority order (correctness > maintainability > polish),
tighten comment style to default-no-comment with why-only rationale,
and document splitting skill workflow from reference sub-docs.

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

@@ -14,6 +14,7 @@ Scaffold a new skill directory with a `SKILL.md` and optional helper scripts und
 ### 1. Gather Requirements
 
 Ask the user:
+
 - **What does the skill do?** (trigger conditions, purpose)
 - **Are there repeatable commands?** (if yes, these become scripts)
 
@@ -26,23 +27,27 @@ 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.>'
+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.
+- **Split workflow from reference when the reference surface grows.** If a skill accumulates lookup tables, mapping rules, or capability references that the workflow consults, move them into a sibling `<skill>/<category>/` directory (e.g. `mappings/`, `references/`) with one sub-doc per category and an index `README.md`. Keep `SKILL.md` focused on the hot path — workflow, hard rules, and a short table pointing at the sub-docs. Include a brief style guide in the index README covering (a) defer to authoritative sources (stubs, schemas, generated docs) whenever possible, (b) row/entry formatting conventions, (c) when to create a new sub-doc vs. extend an existing one.
 
 ### 3. Present for Review