Yes, I think Jarek summarized it correctly. The proposal is separate from the symlink mechanism itself — the idea is to move the adoptable skills into a separate canonical folder.
When a maintainer in an adopting project runs `/setup-steward` in their project clone, steward can still expose those skills through symlinks exactly as today. So from the adopter side, the behavior does not really change. However, from the Magpie framework-development side, we no longer need to load the entire adoptable skill set into context during normal framework maintenance workflows. It also gives us room for future vendor extensibility, and aligns better with potential future directions such as plugin marketplaces or a `skills.sh`-style distribution model where skills exist in a vendor-neutral canonical layout. https://code.claude.com/docs/en/skills#where-skills-live https://github.com/vercel-labs/skills#skill-discovery And because the framework-maintenance skills and adoptable payload skills become cleanly separated, self-adopt workflows can much more closely mirror the real adopter experience as well. On 2026/05/28 00:00:11 Jarek Potiuk wrote: > > The apache grails project uses git symlinks to point Claude-specific > locations to the standard locations. See: > https://github.com/apache/grails-core/blob/HEAD/CLAUDE.md > > Yep. We do the same in "adopting" projects (we even handle 4 different > cases of symlinking ;)) .But this proposal is a little different proposal. > We still want to symlink the skills used when developing Apache Magpie. > However, Yeonguk proposes moving the "adoptable" skills to a new folder. > These are skills not run in Magpie, but any adopting project will get them > symlinked from the steward after a maintainer runs "/setup-steward" in > their project clone. > > On Wed, May 27, 2026 at 10:40 PM James Fredley <[email protected]> > wrote: > > > The apache grails project uses git symlinks to point claude specific > > locations to the standard locations. See: > > https://github.com/apache/grails-core/blob/HEAD/CLAUDE.md > > > > James Fredley > > > > On 2026/05/27 18:40:20 Yeonguk Choo 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 > > > > > >
