feat: Phase 0 skill portability for the open standard#230
Open
ryzizub wants to merge 8 commits into
Open
Conversation
Strengthen graceful degradation so skills run on non-Claude harnesses (Codex, Gemini, OpenCode). Adds structured sequential-pass review fallbacks, destructive-op guards on create-pr and rebase, AskUserQuestion and allowed-tools fallbacks via a shared interaction-fallbacks reference, a portable clear-context handoff, and an off-Claude create port with an inline companion catalog. Also includes the Phase 0 audit groundwork (validate-skill CI, CONTRIBUTING cross-harness section, context7 degradation). Refs #228 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Complete the remaining #228 workstreams on top of the cross-harness fallbacks commit: - Rename the review skill to quality-review: the bare name collides with built-in /review commands on Claude Code (flat install), Codex, and Copilot. Full reference sweep; docs/code-review/ output dir and review agent names unchanged. - docs/portability/: reserved-command collision audit (decision rule, per-host evidence, cross-plugin audit) and agent-definition conversion spec (md -> Codex TOML / Gemini md / OpenCode md, worked example). - CI: frontmatter guard (scripts/ci/check-frontmatter.sh) closing the two silent-skip gaps validate-skill leaves open — UTF-8 BOM (Gemini-fatal) and agents/**/*.md frontmatter. - Hotfix push step gains the cross-harness guard the other pushing skills already carry. - context7 mandate in official-docs-research-agent hedged with the web-search fallback. Refs #228 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Revert the quality-review skill back to `review` and handle the Codex and GitHub Copilot built-in `/review` collision in-body (skills activate by description, plus a cross-harness note) instead of via the rename. Remove the docs/portability design docs (agent-definition-conversion, reserved-command-audit) and the CLAUDE.md Reference Docs section, and drop the verbose validate-skill comment in CI. Refs #228 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ryzizub
changed the title
Reframe two npx skills behaviors in CONTRIBUTING as verified/observed rather than documented (symlink dereference confirmed locally with skills CLI v1.5.20; unknown-field handling observed from source), and note metadata: as the strict- conformance escape hatch. Complete the quick-start name rule (directory match, hyphen and length constraints). Link the shared interaction-fallbacks note from brainstorm, debrief, plan, and plan-technical-review so all AskUserQuestion-using skills carry the degradation pointer. Refs #228 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
6 tasks
…docs Move scripts/ci/check-frontmatter.sh to .github/scripts/check-frontmatter.sh (update the ci.yaml run step and both CONTRIBUTING references). Correct the shared-symlink install docs: the skills CLI's download endpoint (skills.sh/api/download) is not served today and returns 404, so a github: install falls back to fetching from GitHub and copying. Scope what is actually verified (copy-and-dereference) versus not (full end-to-end github: install). Refs #228 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ugin-reusable-fbd5aa
ryzizub
added a commit
to VeryGoodOpenSource/vgv-ai-flutter-plugin
that referenced
this pull request
Jul 24, 2026
Match the CONTRIBUTING frontmatter guidance in VeryGoodOpenSource/vgv-wingspan#230: the spec's optional skills-ref linter rejects top-level fields outside the six it allows, and nesting the Claude Code extras under metadata: is the escape hatch if strict conformance is ever needed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Remove cross-host rationale and maintainer notes that explained behavior to a reader rather than instructing the model, keeping every runtime fallback intact. Drops the /review cross-harness note, the disable-model-invocation explanations in the create-pr and rebase guards, the hooks/ absence rationale and table sync note in create, the slash-form aside in the clear-context handoff, and the host taxonomy and allowed-tools history in interaction-fallbacks. The rationale lives in CONTRIBUTING. Refs #228 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ryzizub
added a commit
to VeryGoodOpenSource/vgv-ai-flutter-plugin
that referenced
this pull request
Jul 24, 2026
Reconcile with VeryGoodOpenSource/vgv-wingspan#230: name the non-Claude harnesses (Codex, Gemini CLI, OpenCode) the portability section targets, and state the full spec-conformance rules for the skill name field (kebab-case, no leading/trailing/consecutive hyphen, 1-64 chars, matches the directory). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ryzizub
marked this pull request as ready for review
July 24, 2026 15:32
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Phase 0 of the open-standard epic (#228): make the 12 Wingspan skills portable to non-Claude harnesses (Codex, Gemini CLI, OpenCode) via the Agent Skills standard, without changing Claude Code behavior. Single-source
SKILL.mdplus in-body graceful degradation, no build step.Changes
Portability prep
namematches its directory (enforced in CI via.github/scripts/check-frontmatter.sh+ thevalidate-skilljob).$ARGUMENTSand${CLAUDE_SKILL_DIR}each carry a fallback that fires when the host does not substitute them.context7MCP references degrade to web search when the server is absent.Fallbacks and safety (in-body)
create-prandrebaserefuse push, PR, or history rewrite without an explicit user instruction.AskUserQuestionandallowed-toolsfallbacks in a sharedinteraction-fallbacks.md, symlinked into every skill that uses them.createdegrades off Claude Code to an inline, tech-agnostic companion catalog instead of the plugin-roothooks/and theSkilltool.CONTRIBUTING.mdrather than left as meta-commentary in the bodies.Decisions
reviewkeeps its bare name. The Codex and GitHub Copilot built-in/reviewcollision is handled by description-based activation (the skill triggers on the request, not the typed slash command). The rationale is recorded inCONTRIBUTING.mdunder "Reserved slash-command names", not as an in-body note.Verified locally
skillsCLI (v1.5.20) installed all 12 skills from this branch and dereferenced every shared symlink into a real file, exec bits preserved, zero dangling links. No materialization needed.skills.sh/api/download/...) is not served today (returns 404), so agithub:install falls back to fetching from GitHub and copying. The copy-and-dereference step is confirmed; a full end-to-endgithub:install is not yet verified.Not in this PR (follow-ups for #228)
Refs #228
🤖 Generated with Claude Code