Actually - I think it is important however that we want to dogfood Magpie on Magpie :) . See the discussion on good first issue skill https://github.com/apache/airflow-steward/pull/353
So I think what we should end up with that: a) yes we keep skills separately b) (and here comes inception!!! ) Magpie should adopt itself :) J. On Fri, May 29, 2026 at 9:45 AM Yeonguk Choo <[email protected]> wrote: > 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 > > > > > > > > > >
