docs: document the agent skills system

[geoffjay]

Adds comprehensive documentation for the agent skills system and example skills in .agentd/skills/.

New files:

• docs/agent-skills.md — full guide covering skill format, discovery, assignment, materialization, CLI usage, best practices, and troubleshooting
• .agentd/skills/git-spice/SKILL.md — branch stacking reference for agents
• .agentd/skills/agent-memory/SKILL.md — memory service operations reference
• .agentd/skills/example/SKILL.md — minimal skill template for authors

Doc sections: Overview, file format, discovery paths, assigning via YAML, materialization behavior, CLI commands, writing tips, troubleshooting, API/Rust reference.

Closes #1215

[geoffjay]

Review: docs: document the agent skills system

Stack Position

Branch issue-1215 is stacked on issue-1214 (PR #1231). Full chain: main ← epic-1209 (#1226) ← issue-1210 (#1228) ← issue-1211 (#1229) ← issue-1213 (#1230) ← issue-1214 (#1231) ← issue-1215 (#1232). All parent PRs are in merge-queue.

---

No Blocking Issues

---

Non-Blocking: Worktree + additional_dirs Claim Is Overstated

From docs/agent-skills.md:

The agent's additional_dirs configuration (already wired through build_claude_command) points back at the project root, so Claude Code discovers the skills via the parent directory mechanism.

The first part is accurate — additional_dirs is passed through build_claude_command as --add-dir flags. But "points back at the project root" is only true if the agent YAML explicitly lists the project root in additional_dirs. For worktree agents, the orchestrator materializes skills into working_dir/.claude/skills/ (the source working directory), but Claude Code starts inside the worktree — not working_dir. Skills are only reachable from inside the worktree if additional_dirs was manually configured to include working_dir.

The current code does not automatically add the project root to additional_dirs for worktree agents. A more accurate statement:

Skills are written to <working_dir>/.claude/skills/ before the agent starts. For worktree agents, Claude Code runs inside the worktree rather than working_dir, so skills will only be available if the agent template's additional_dirs includes the source working_dir (the project root). This is not configured automatically.

---

Non-Blocking: Skill Struct Reference Omits a Field Without Explanation

The Reference section shows:

pub struct Skill {
    pub name: String,
    pub description: Option<String>,
    pub content: String,
}

The actual struct has a fourth field (source_path: PathBuf) that is pub(crate) and #[serde(skip)]. Omitting it is correct for API/serialization documentation, but a brief note would prevent confusion for contributors reading the struct definition in source:

    // source_path: PathBuf  — internal only, omitted from API responses

---

What's Working Well

• Accuracy throughout: all implementation details check out against the source — discovery paths, SKILL.md target path, skip-existing behavior, soft-failure on missing skills, sorted output.
• MaterializeResult reference: correctly shows written, skipped, not_found matching the actual struct. ✓
• API reference: correctly notes that source_path is omitted from GET /skills responses. ✓
• git-spice/SKILL.md: The > [!IMPORTANT] **All agent usage MUST include --no-prompt** constraint is essential and well-placed. Branch naming conventions and "never use git checkout -b" constraints match CLAUDE.md. ✓
• agent-memory/SKILL.md: Correct flag names (--created-by, --as-actor, --type, --tags). "What NOT to Remember" guidance mirrors the reviewer agent's own protocol. ✓
• example/SKILL.md: Useful minimal template with correct format guidance. "Write skills as instructions to the agent, not documentation for humans" is the right framing. ✓
• Troubleshooting section: actionable and covers the real failure modes (wrong path, wrong extension, case-sensitive SKILL.md, CWD dependency). ✓
• CLI output example: table shows skills in alphabetical order (agent-memory, example, git-spice), consistent with discover_all_skills() global sort. ✓

---

Summary

Two non-blocking notes: the worktree paragraph overstates that additional_dirs automatically provides skill access (it requires explicit configuration), and the Skill struct reference would benefit from a note about the omitted source_path field. Everything else is accurate and well-written. Adding to merge-queue — this is the final PR in the #1208 skills epic.