Repository navigation
[Feature]: Add extension.yml-controlled skill resource copying with legacy no-copy support #5366
Description
Problem Statement
Extension commands rendered as agent skills currently leave their supporting files under .specify/extensions/<id>/ and rewrite references in the generated SKILL.md to that location. #5363 documents the resulting path-resolution problems; #5364 addresses the rewriting approach.
We also need a packaging option that places bundled resources alongside the generated skill, instead of requiring every resource reference to reach back into the installed extension. This is a separate feature from fixing the existing no-copy route, which must remain supported.
The Agent Skills specification describes a skill directory containing instructions and optional scripts, references, and assets. Its file-reference guidance says:
When referencing other files in your skill, use relative paths from the skill root.
This supports self-contained packaging of bundled skill resources, although the specification does not prohibit external dependencies or guarantee a shell working directory.
Proposed Solution
Add an extension.yml configuration mechanism for skill resource delivery, with both modes supported:
| Mode | Resource location | Intended role |
|---|---|---|
| Copy alongside the skill | Required bundled resources are copied into each generated skill directory and referenced relative to that directory. | Preferred model for new extension authoring. |
| No copy / extension-local | Resources remain under .specify/extensions/<id>/; generated skills reference their installed locations. |
Deprecated but still supported compatibility route. |
For example, copy mode could produce:
.github/skills/speckit-example-review/
├── SKILL.md
└── references/
└── reviewer.md
The skill would reference references/reviewer.md rather than ../../../.specify/extensions/example/references/reviewer.md.
The installed extension remains the source of truth. Skill-local files are generated installation outputs, not independently maintained source copies. Use regular files for copy mode; do not make symlink support a prerequisite.
This follows @mnriem's direction in the discussion on #5363:
We would need to support both. The alongside as the new normal and the in the extension as the deprecated but still supported route
It would be part of the extension.yml I would think
The original proposal was opt-in copying. The maintainer's reply establishes alongside delivery as the intended new normal while retaining the legacy route. The precise manifest syntax and transition/default rules still need design; this issue does not treat them as already agreed.
Scope and compatibility
- Configure the delivery mode in
extension.yml; a CLI override is not required for this feature. - Define which resources belong to each skill and how source paths map to skill-local destinations. Do not blindly copy the entire extension or rely on ambiguous filename matching.
- Cover all extension skill-generation and restoration routes, including aliases where generated, integration refresh/switch, and restoration after preset overrides.
- Track copied output ownership for refresh, update, removal, rollback, and changes between modes. Preserve unrelated or user-modified files according to the existing ownership policy.
- Do not silently relocate shared configuration or change scripts' required working directories. Document how such dependencies behave in both modes.
- Leave non-skill command output behavior unchanged.
- Keep existing extensions working during adoption. Document how manifests without the new setting are interpreted; deprecation must not mean removal of the no-copy route.
Design questions to resolve
- What is the manifest field/value schema, and is resource selection configured per extension or per command/skill?
- How do older manifests retain compatibility while new authoring guidance or scaffolding adopts alongside delivery?
- How are resource mappings, shared resources, and script dependencies declared or resolved deterministically?
Alternatives Considered
- Path rewriting only: remains necessary for the supported no-copy route, but does not provide skill-local packaging.
- Symlinks: avoid duplicate bytes but are not a portable baseline. fix: write Codex dev skills as files #2988 documents a Codex limitation for symlinked
SKILL.mdfiles; that does not establish whether linked resource files work, so resource-link compatibility would need separate validation. - CLI-only opt-in: does not express an extension's packaging intent in its manifest; the maintainer favored
extension.yml. - Unconditional copying: would remove the required no-copy option and could alter shared configuration or script behavior.
Component
Agent integrations (command files, workflows), with extension manifest and lifecycle support in Specify CLI.
AI Agent (if applicable)
All integrations that render extension commands as skills. Actual resource resolution and script execution must be validated in representative agents rather than inferred from the presence of SKILL.md alone.
Use Cases
- An extension author bundles reference documents or templates with a skill and wants ordinary skill-relative references.
- An existing extension relies on centrally installed resources or shared configuration and must continue using the no-copy route.
- A user updates an extension or switches integrations and expects the selected delivery mode and its generated resources to remain consistent.
Acceptance Criteria
- A documented and validated
extension.ymlcontract supports both copy and no-copy delivery, including a defined compatibility rule for manifests without the setting. - New authoring guidance favors alongside delivery; the deprecated no-copy route remains usable and tested.
- Copy mode installs the required resources as regular files with working skill-relative references, without requiring symlinks.
- No-copy mode continues to resolve resources from the installed extension and does not create resource copies.
- Install, refresh/update, integration switch, preset restoration, removal, rollback, and transitions between modes handle owned outputs consistently and preserve user/unrelated files.
- Positive and negative tests cover both modes, resource mappings, invalid configuration, missing or unsafe resources, destination conflicts, and non-skill output regressions.
- Script working-directory requirements and shared configuration semantics are preserved and documented; behavior is validated on supported platforms, including Windows without symlink privileges.
- Manual agent-level evidence demonstrates resource access for representative skill integrations in both modes.
- Extension authoring and architecture documentation explain the mode selection, resource layout, lifecycle behavior, and migration policy.
Additional Context
- Original bug: [Bug]: Extension skill references are rewritten to project-root-relative paths and miss nested directories #5363.
- Related path-rewriting fix: [bug-fix] Fix extension-skill-path-rewrite: rewrite extension refs for skills #5364. This feature does not replace the need for a working no-copy path.
- Proposal and rationale.
- Maintainer direction is quoted above; detailed implementation and migration choices remain open.
- Existing bug evidence is linked from [Bug]: Extension skill references are rewritten to project-root-relative paths and miss nested directories #5363. No new implementation or runtime validation has been performed for this feature request.
AI Disclosure
Created for @markuswondrak using pi with GitHub Copilot / gpt-6-astra, in interactive, human-directed mode. AI assistance covered reading the linked discussion and repository guidance, drafting this issue, and publishing it at the contributor's request. No code changes or runtime tests were performed.
Activity
github-actions commentedon Nov 10, 2026
Feature assessment — extension-resource-delivery · Stage 1/5: Intake
Idea Intake: Extension-managed skill resource delivery modes
Idea (as captured)
Restated
The request is to make skill resource placement configurable in
extension.ymlso extension authors can package referenced files directly with generated skills while preserving the existing extension-local reference model for backward compatibility. It asks for a first-class, lifecycle-safe contract instead of ad-hoc path rewriting only.Origin & Context
First-Glance Unknowns
github-actions commentedon Nov 10, 2026
Feature assessment — extension-resource-delivery · Stage 2/5: Research
Idea Research: Extension-managed skill resource delivery modes
Users & Demand
.specify/extensions/<id>/and relies on rewrite semantics. — [source:src/specify_cli/agents.pyrewrite_extension_paths,docs/extensions/developing.mdscript-path rewriting section] (confidence: high)Prior Art
design/extension.mdcommand/skill delivery and refresh/removal sections] (confidence: high).specify/extensions/<id>/..., which confirms no-copy mode is established and regression-sensitive. — [source:tests/test_extension_skills.pyaroundtest_skill_registration_rewrites_extension_subdir_paths] (confidence: high)Market & Context
Data & Constraints
provides.commands|templates|scripts|config, hooks, and events; no dedicated resource-delivery mode field is documented in existing manifest contract text. — [source:design/extension.mdmanifest contract section;docs/extensions/developing.mdmanifest examples] (confidence: high).specify/extensions/<id>/..., so introducing copy mode must avoid regressing this compatibility route. — [source:src/specify_cli/agents.pyrewrite_extension_paths;tests/test_extension_skills.py] (confidence: high)src/specify_cli/extensions/__init__.pyremoval/rollback code paths;design/extension.md] (confidence: medium)Evidence Against the Idea
design/extension.md] (confidence: medium)Gaps & Open Questions
extension.ymlschema for selecting delivery mode and resource mappings.]Sources
src/specify_cli/agents.py(local repository source)src/specify_cli/extensions/__init__.py(local repository source)tests/test_extension_skills.py(local repository source)design/extension.md(local repository source)docs/extensions/developing.md(local repository source)github-actions commentedon Nov 10, 2026
Feature assessment — extension-resource-delivery · Stage 3/5: Problem
Problem Definition: Skill resource packaging for extensions
Problem Statement
Extension-authored skills need resource references that resolve reliably across agent integrations and lifecycle operations, but current extension-local delivery requires path rewriting and layout awareness that can be fragile and hard for authors to reason about. The project needs a clear, backward-compatible contract for how skill resources are delivered and maintained.
Affected Users & Stakeholders
Goals
Non-Goals
Success Metrics
Cost of Inaction
Spec Kit keeps relying on extension-local rewrites only, leaving authoring ergonomics and some integration/path expectations unresolved; repeated defects and ambiguity around resource placement policy are likely to recur, raising maintenance/review cost and reducing confidence in extension skill portability.
Open Questions
extension.ymlfield schema and granularity (extension-wide vs command/skill-specific).]github-actions commentedon Nov 10, 2026
Feature assessment — extension-resource-delivery · Stage 4/5: Concept
Concept: Manifest-controlled skill resource delivery
Options
Option A — Dual-mode manifest with explicit resource mapping
extension.ymldelivery section that supports two explicit modes:copy(resources copied into each generated skill directory) andno-copy(current extension-local resolution). Authors declare which files are bundled for each skill and destination paths under that skill.Option B — Keep no-copy only, harden rewrite rules further
Option C — Auto-copy all extension resources into each generated skill
Recommendation
Choose Option A. It directly addresses the feature request and maintainer direction (copy-as-normal + retained no-copy compatibility) while preserving a clear migration story. It contains complexity by forcing explicit declarations instead of heuristic full-tree copying and keeps compatibility guardrails explicit.
Out of Scope (for the recommended option)
Assumptions to Validate
github-actions commentedon Nov 10, 2026
Feature assessment — extension-resource-delivery · Stage 5/5: Decision — verdict go
Decision: Manifest-controlled extension skill resource delivery
Scorecard
Verdict & Rationale
go. The problem is real, scoped, and strategically aligned, and there is a credible concept (dual-mode manifest contract) that preserves backward compatibility while enabling the requested packaging model. Evidence is not exhaustive across every runtime, but it is sufficient for specification, provided the spec explicitly addresses lifecycle ownership, migration defaults, and integration validation.
If needs-clarification
If go — Handoff to
__SPECKIT_COMMAND_SPECIFY__extension.ymlcontract (copy+ legacyno-copy) with explicit per-skill resource mappings.