Add metadata.internal: true to all authored skills + improve skills documentation routing

[schrockn]

This commit marks all 20 erk-authored skills in .claude/skills/ with metadata.internal: true to hide them from public discovery on skills.sh and the npx skills CLI. It also improves documentation discoverability by adding a "Skills, SKILL.md, capabilities" row to the AGENTS.md routing table, adding a callout for skill modifications, and enhancing the docs/learned/index.md categories section with skill-focused guidance.

Key Changes

• Add metadata.internal: true to all 20 authored skills in .claude/skills/ (ci-iteration, cli-skill-creator, cmux, command-creator, dignified-code-simplifier, erk-diff-analysis, erk-exec, erk-gt, erk-planning, erk-skill-onboarding, gh, learned-docs, npx-skills, objective, pr-feedback-classifier, pr-operations, refac-cli-push-down, refac-module-to-subpackage, rename-swarm, session-inspector)
• Add skills/capabilities row to AGENTS.md documentation-first discovery routing table
• Add "Adding or modifying skills?" callout in AGENTS.md linking to NPX Skill Management guide
• Document metadata.internal field in docs/learned/capabilities/npx-skill-management.md with explanation and examples
• Update docs/learned/index.md capabilities category with description and read-when guidance

Files Changed

Modified (23 files)

• .claude/skills/ci-iteration/SKILL.md — Added metadata.internal field
• .claude/skills/cli-skill-creator/SKILL.md — Added metadata.internal field
• .claude/skills/cmux/SKILL.md — Added metadata.internal field
• .claude/skills/command-creator/SKILL.md — Added metadata.internal field
• .claude/skills/dignified-code-simplifier/SKILL.md — Added metadata.internal field
• .claude/skills/erk-diff-analysis/SKILL.md — Added metadata.internal field
• .claude/skills/erk-exec/SKILL.md — Added metadata.internal field
• .claude/skills/erk-gt/SKILL.md — Added metadata.internal field
• .claude/skills/erk-planning/SKILL.md — Added metadata.internal field
• .claude/skills/erk-skill-onboarding/SKILL.md — Added metadata.internal field
• .claude/skills/gh/SKILL.md — Added metadata.internal field
• .claude/skills/learned-docs/SKILL.md — Added metadata.internal field
• .claude/skills/npx-skills/SKILL.md — Added metadata.internal field
• .claude/skills/objective/SKILL.md — Added metadata.internal field
• .claude/skills/pr-feedback-classifier/SKILL.md — Added metadata.internal field
• .claude/skills/pr-operations/SKILL.md — Added metadata.internal field
• .claude/skills/refac-cli-push-down/SKILL.md — Added metadata.internal field
• .claude/skills/refac-module-to-subpackage/SKILL.md — Added metadata.internal field
• .claude/skills/rename-swarm/SKILL.md — Added metadata.internal field
• .claude/skills/session-inspector/SKILL.md — Added metadata.internal field
• AGENTS.md — Added skills routing row and modifying skills callout
• docs/learned/capabilities/npx-skill-management.md — Added metadata.internal section
• docs/learned/index.md — Enhanced capabilities category description

original-plan

Plan: Add metadata.internal: true + improve skills documentation routing

Context

Skills in this repo appeared on the skills.sh public leaderboard. While investigating, we found that docs/learned/capabilities/npx-skill-management.md already documents the distinction between authored and npx-installed skills — but it wasn't discovered because nothing in AGENTS.md routes to it. The existing doc is good; the problem is discoverability.

Part 1: Add metadata.internal: true to authored skills

Add metadata.internal: true to all 20 SKILL.md files in .claude/skills/. The 5 symlinked skills in .agents/skills/ are installed from external repos and should NOT be modified here.

metadata:
  internal: true

Files (20 total) — all .claude/skills/:
ci-iteration, cli-skill-creator, cmux, command-creator, dignified-code-simplifier, erk-diff-analysis, erk-exec, erk-gt, erk-planning, erk-skill-onboarding, gh, learned-docs, npx-skills, objective, pr-feedback-classifier, pr-operations, refac-cli-push-down, refac-module-to-subpackage, rename-swarm, session-inspector

Part 2: Fix documentation routing in AGENTS.md

2a. Add skills/capabilities row to the routing table (~line 170)

Add to the "Topic Area | Check First" table:

| Skills, SKILL.md, capabilities | `docs/learned/capabilities/`                 |

File: AGENTS.md line ~178 (after the TUI row)

2b. Add routing to "Skill Loading Behavior" section (~line 148)

Expand the section to point to the detailed doc when modifying or adding skills:

**Modifying skills?** Read [NPX Skill Management](docs/learned/capabilities/npx-skill-management.md) first — covers authored vs npx-installed skills, `metadata.internal`, `skills-lock.json`, and the `_UNBUNDLED_SKILLS` registry.

File: AGENTS.md line ~155 (after the npx skills one-liner)

2c. Add description to capabilities category in docs/learned/index.md

Change the bare - [capabilities/](capabilities/) line to include a description and read-when guidance, matching the style of other categories like cli/ and hooks/.

File: docs/learned/index.md line 12

Part 3: Add metadata.internal section to npx-skill-management.md

Add a section to the existing doc covering:

• What metadata.internal: true does (hides from npx skills CLI discovery and skills.sh)
• Why all erk-authored skills use it (private repo, not for public consumption)
• NPX-managed skills are controlled by their source repos, not modified here

File: docs/learned/capabilities/npx-skill-management.md (new section after the comparison table)

Verification

• grep -r "internal: true" .claude/skills/ → 20 matches
• grep -r "internal: true" .agents/skills/ → 0 matches
• AGENTS.md routing table includes skills/capabilities row
• "Skill Loading Behavior" section links to the detailed doc
• docs/learned/index.md capabilities category has description

plan-header

schema_version: '2'
created_at: '2026-03-30T12:34:37.319870+00:00'
created_by: schrockn
branch_name: plnd/add-skill-internal-metadat-03-30-1234
created_from_session: 3ac422ef-50e6-4b8c-834d-65d4f04eb1fb
lifecycle_stage: impl
worktree_name: erk-slot-06
last_local_impl_at: '2026-03-30T16:40:37.331990+00:00'
last_local_impl_event: ended
last_local_impl_session: 9409898c-c91e-431d-a975-8a65cdb45b91
last_local_impl_user: schrockn
last_session_branch: planned-pr-context/9410
last_session_id: 9409898c-c91e-431d-a975-8a65cdb45b91
last_session_at: '2026-03-30T12:40:41.137499+00:00'
last_session_source: local

---

To replicate this PR locally, run:

erk slot teleport 9410

[schrockn]

🚀 Starting implementation

---

Worktree: erk-slot-06
Branch: plnd/add-skill-internal-metadat-03-30-1234

[schrockn]

• Add metadata.internal: true to all authored skills + improve skills documentation routing #9410 👈 (View in Graphite)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

✅ Audit PR Docs

Last updated: 2026-03-30 10:24:58 PT

Found 0 violations across 1 file. No inline comments needed.

Details

Patterns Checked

✅ Verbatim code blocks — None found
✅ Inaccurate claims — None found (prior inaccurate count claim already fixed in this PR)
✅ Duplicative sections — None found
✅ Drift risk in new content — None found

Doc Audit: docs/learned/capabilities/npx-skill-management.md

Verdict: KEEP | Duplicative: ~5% | High Value: ~70%

New metadata.internal section (lines 87–101):

• YAML example block: TEMPLATE (One Code Rule exception — format/pattern example, not verbatim source)
• Prose: HIGH VALUE — documents non-obvious intent of the field and the anti-pattern for NPX-managed skills

Pre-existing issues (outside diff, not inline-commentable):

• Lines 60, 64: DRIFT RISK — line-range source pointers (bundled.py:17-38) will drift
• Lines 50–56: DRIFT RISK — enumerated skill list ("as of writing") will go stale

These were flagged in the prior audit run.

Files Reviewed

• docs/learned/capabilities/npx-skill-management.md: 0 violations

---

Activity Log

• 2026-03-30 10:24:58 PT: Audited 1 doc: KEEP. New metadata.internal section is clean (TEMPLATE + HIGH VALUE). 0 violations in diff. Pre-existing drift risks at lines 60, 64, 50–56 noted (outside diff).
• 2026-03-30 09:44:55 PT: Audited 1 doc: 1 SIMPLIFY. Found 1 inaccurate claim (skill count: 20 vs actual 25) in new metadata.internal section. 2 pre-existing drift risks in line-range source pointers (lines 60, 64) — outside diff, not inline-commentable.

[schrockn]

@github-actions[bot] commented:

❌ Audit PR Docs

Last updated: 2026-03-30 09:44:55 PT

Found 1 inline violation + 2 pre-existing issues (noted below, not inline-commentable as they are outside the diff). Inline comments posted for new violations.

Details

> ...

Addressed: Removed the hardcoded count — now says "all erk-authored skills in .claude/skills/" to avoid drift as skills are added/removed.

---

_{Addressed via /erk:pr-address at 2026-03-30 05:20 PM UTC}