> 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 > > >
