PUP-581: Split code-puppy-agent skill into topic reference docs, add namespace_skill_search coverage

[thomwebb]

Jira: PUP-581

What

Splits the monolithic code-puppy-agent skill's SKILL.md (632 lines,
~24KB) into an index file plus six topic-specific reference files that
the model reads on demand via read_file. Also updates the skill's
content to document the new namespace_skill_search plugin (#713) and
two hook-system gotchas discovered while building it.

Why

• SKILL.md was already over the project's own 600-line file cap
  before this PR touched it.
• It didn't cover namespace_skill_search at all (skill namespaces,
  the browse_skill_namespace tool, the get_model_system_prompt
  last-write-wins gotcha, the import-time-vs-startup-callback gotcha).
• Splitting means activating the skill now costs ~8KB (the index) in
  the common case instead of ~24KB (everything), with topic detail
  available on demand for whichever question is actually being asked.

Files

• SKILL.md -- trimmed to: architecture diagram, a reference map table,
  condensed dev conventions, and the quick file-map table.
• AGENTS_AND_TOOLS.md, PLUGINS_AND_CALLBACKS.md, MODELS_AND_MCP.md,
  SESSIONS_AND_HISTORY.md, SKILLS_SYSTEM.md,
  SYSTEM_PROMPT_CONFIG_AND_I18N.md -- one topic each.
• register_callbacks.py docstring updated to explain the split and a
  real gotcha it documents: plugin-registered skills (skill_md_path)
  don't auto-surface sibling files through activate_skill's
  resources field the way a real filesystem skill directory does, so
  the reference files are linked by plain repo path in SKILL.md's
  prose instead.

Known tradeoffs (raised and accepted before merging, not discovered after)

• Broad "explain the whole architecture" questions now cost multiple
  read_file round-trips instead of one activate_skill call.
• Relies on the model actually following the index's pointers to the
  right reference file -- nothing enforces that; a weaker model could
  answer shallowly from the index alone instead of fetching detail.
• Reference file paths are plain prose in SKILL.md, not validated by
  any test -- a future rename would silently break a pointer.
• No before/after eval showing this improves model answers. This is
  optional cleanup justified by analogy to namespace_skill_search's
  reasoning (smaller context on demand beats one big flat block), not a
  proven fix for an observed problem -- nobody had reported the skill
  as too expensive to activate before this PR.
• Other known duplicate copies of this skill (internal fork, other
  worktrees) now have more files to keep in sync if anyone syncs them.

Testing

• 225 existing plugin/skill tests pass, no regressions
  (tests/plugins/test_agent_skills*.py, test_plugins_init*.py,
  test_plugin_meta.py, test_builtin_plugin_lock.py).
• ruff check / ruff format --check clean on the plugin directory.
• Verified parse_skill_metadata() parses the new frontmatter (skill
  version bumped 1.1 -> 2.0) without error.
• No dedicated new tests added -- this is a content/structure change to
  a skill's documentation, not new executable behavior.

Related

Builds on #713 (namespace_skill_search plugin) -- that PR documents
the feature from the user-facing "how do I use it" angle in
docs/AGENT_SKILLS.md; this PR documents it from the "how does Code
Puppy work internally" self-awareness angle covered by this skill.