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
