Good Idea. On Wed, May 27, 2026 at 8:40 PM Yeonguk Choo <[email protected]> wrote:
> Hi all, > > I'd like to propose a layout change to the framework repo: > move the canonical home of our 28 payload skills from `.claude/skills/` to > a top-level `skills/` directory, > and reserve `.claude/skills/` for framework-dev-only items (plus the > gitignored symlinks that self-adopt wires up). > > == Why == > > Today every skill ships under `.claude/skills/`, which is the > Claude-Code-specific convention. Three consequences: > > 1. Adopters on non-Claude harnesses (Cursor's `.cursor/rules/`, > Codex's own conventions, etc.) cannot consume our framework > without re-layout work. The framework deliverable shouldn't > be hard-coded to one harness's directory shape. > > 2. The framework repo's own `.claude/skills/` mixes two unrelated > things: deliverable framework payloads (issue-triage, > pr-management-*, security-*, …) and framework-maintenance > skills (write-skill, setup-steward). Different audiences, > different lifecycle. > > 3. Because all payload skills currently live under > `.claude/skills/`, they are also loaded during framework > development itself. Moving the canonical payloads into > `skills/` avoids loading the entire deliverable skill set > during normal framework-maintenance workflows, while still > allowing targeted self-adopt exposure where needed. > > Proposed split: > > skills/ canonical payload (vendor-neutral) > .claude/skills/write-skill/ the only framework-dev skill we > ship directly in .claude/ > .claude/skills/<others> gitignored symlinks, created at > runtime by tools/dev/bootstrap.sh > or by /setup-steward self-adopt > > This sets up — but does NOT add in this PR — a future > `adapters/<vendor>/` layer that transpiles `skills/<n>/SKILL.md` > into whatever shape Cursor, Codex, or any other harness expects. > > == What it does NOT change == > > - Adopter repos: setup-steward still installs skills into the > adopter's `.claude/skills/`. Patterns A/B/D detection is > untouched. No adopter-visible behaviour changes. > > - SKILL.md format: same YAML frontmatter shape as today. > > - Skill content: only paths/links updated. > > == Current design assumptions (open to challenge) == > > 1. Canonical SKILL.md format = current Claude-Code shape, over > inventing a vendor-neutral spec. Adapters transpile later; > we avoid introducing and maintaining a separate intermediate > spec up front. > > This also keeps the framework aligned with the emerging > Claude ecosystem and future marketplace/distribution formats, > rather than inventing a parallel format prematurely. > > 2. Snapshot internal layout follows source: snapshots become > `.apache-steward/skills/<n>/` (not > `.apache-steward/.claude/skills/<n>/`), so source and > snapshot stay in lockstep. > > > == Sequencing == > > One related workstream is the pending rename to > `apache-magpie`. > > At the moment, I suspect it may be cleaner to land the rename > first and do this layout restructure afterward, so the > directory moves happen against the final repository > naming/layout only once. > > Vendor adapters (Cursor, Codex, …) would still go in separate > follow-up PRs and are not blockers for this restructure. > > And if anyone sees a substantially simpler or cleaner approach, > I'd very much like to hear it. > > Thanks, > Yeonguk > > -- > 추영욱 Yeonguk Choo > > Mobile +82-10-8815-8118 > Email [email protected] <[email protected]> > FB23 00B5 EAA3 EBF0 FDD6 C2B9 BE7A 512C BC72 067A >
