docs(#844): add skill documentation altitude guidance

[fullsend-ai-coder]

Summary

• Adds a new section 3 ("Skill documentation altitude") to AGENTS.md establishing that SKILL.md files should stay at the directive altitude: describe what to detect, what patterns to match, and what to report — not specific CLI commands, API queries, or pagination strategies.
• When a skill section references external data, it should name the data source and fields needed, not the exact retrieval commands. Implementation mechanics are delegated to subagent prompts or existing skill infrastructure.
• Renumbers existing sections 3–8 to 4–9 to accommodate the insertion.

Context

PR #540 went through 7 review rounds over 18 days as a conceptual skill doc addition progressively expanded into a detailed engineering specification. The core issue was an altitude mismatch: skill documentation drifted from "what patterns to detect" into "how to query GitHub Actions APIs." This guidance gives reviewers a citable standard to flag that drift early.

Test plan

• Verify the new section is placed after "Simplicity first" (section 2) and before "Surgical changes" (section 4)
• Verify all subsequent sections are correctly renumbered (3→4, 4→5, 5→6, 6→7, 7→8, 8→9)
• Verify the guidance covers all three validation criteria from the issue: directive altitude, data-source naming, and delegation to subagent prompts
• Verify pre-commit hooks pass (trailing whitespace, end-of-file, gitlint)

---

Closes #844

Post-script verification

• Branch is not main/master (agent/844-skill-doc-altitude)
• Secret scan passed (gitleaks — 1a3086f5512b3700ab8e081c689cc7586c9af20f..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:06 PM UTC · Completed 1:28 PM UTC

Commit: 5a116a1 · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The PR is linked to issue AGENTS.md should include altitude guidance for skill documentation #844 and provides clear rationale for the change (adding skill documentation altitude guidance to prevent review-cycle inflation on skill PRs). Human approval is always required for protected-path changes, regardless of context.

---

Labels: Docs-only change to AGENTS.md adding skill documentation altitude guidance.