feat: document custom skill paths in plugin.json

[galligan]

Summary

The plugin.json manifest supports custom skill paths via the skills field, which is underdocumented and highly valuable for organizing large plugins.

Discovery

From Claude Code plugins-reference:

Field	Type	Description
skills	string|array	Additional skill directories

Custom paths supplement default directories - they don't replace them.

This enables logical grouping within a single plugin:

{
  "name": "outfitter",
  "skills": [
    "./core/skills/",
    "./authoring/skills/",
    "./workflows/skills/"
  ]
}

Tasks

• Test behavior: Verify how skills from custom paths are namespaced

  • Do skills from ./core/skills/tdd/ appear as /outfitter:tdd?
  • What happens with naming conflicts across paths?
  • Does discovery order matter?

• Document in agent-kit: Add guidance to plugin development skills

  • When to use custom paths vs separate plugins
  • Directory structure patterns for large plugins
  • Namespace behavior with custom paths

• Consider consolidation: This enables consolidating baselayer/agent-kit/gitbutler into single outfitter plugin

  • Eliminates cross-plugin reference friction (baselayer:skill → just skill)
  • Single install experience
  • Maintains logical organization via path grouping

Context

Discovered while discussing plugin architecture simplification. Current multi-plugin setup creates friction with cross-references and version coordination.

Related

• PR feat(baselayer): add context-management skill for state persistence #32 (context-management skill) — added cross-plugin references that would benefit from consolidation