Packaging and Portability

Packaging and Portability

How the two Skills go from source repository to a standalone, portable archive. Canonical: docs/ARCHITECTURE.md §7 and §10, policies/skill-development-policy.md.

Source layout vs. distribution layout

source repository layout            standalone Skill archive
(skills/<name>/, shared/)                (dist/*.zip)
    ↓                                        ↓
skills/<name>/SKILL.md              →   SKILL.md            (archive root)
skills/<name>/runbooks/…            →   runbooks/…
skills/<name>/templates/…           →   templates/…
skills/<name>/policies/…            →   policies/…
skills/<name>/metadata/…            →   metadata/…
shared/policies/…, shared/templates/…  →  shared/policies/…, shared/templates/…

scripts/package-manifest.json is the single source of truth for archive contents. SKILL.md moves from source depth 2 to archive depth 0, so packaging applies a narrow, deterministic link-rewrite across the staged Markdown (../../shared/... → shared/..., and similarly for nested files) — Skill-internal links are untouched, and the canonical source files remain the single source of truth.

Building an archive

./scripts/package-skills.sh local    # -> dist/local-code-review-skill.zip
./scripts/package-skills.sh github   # -> dist/github-pr-review-skill.zip
./scripts/package-skills.sh all      # both

PowerShell: ./scripts/package-skills.ps1 <local|github|all>. Needs the zip/unzip command-line tools on macOS/Linux, or PowerShell on Windows. Archives land under the ignored dist/ directory.

What's never packaged

Repository-development files — AGENTS.md, this repository's policies/, everything under docs/ (including ARCHITECTURE.md and features/), and the root README.md — are never packaged, and no packaged Skill resource may depend on them. A distributed archive must remain fully correct and self-explanatory with those files deleted from the consumer's environment entirely. See policies/skill-development-policy.md, "Packaged Skills Are Independent of Repository-Level Development Instructions."

Runtime portability

The canonical Skill (SKILL.md plus its packaged policies, runbooks, templates, and shared resources) must remain usable on any Agent Skills-compatible runtime — Claude Code, Codex, Cursor, OpenCode, or another. External dependencies are expressed as capabilities (e.g. "authenticated GitHub access with sufficient review permissions"), never as a required vendor-specific tool name.

A runtime adapter (e.g. an optional agents/openai.yaml file) may improve discovery, presentation, or configuration for one consumer, but must never redefine review scope, severity, mutation boundaries, output contracts, or dependency requirements. Ignoring or removing an adapter still leaves a coherent Skill.

Concern	Claude	Codex	Cursor	OpenCode
Canonical directory-based SKILL.md	documented	documented/static validation	documented	documented
Runtime-specific adapter required	no	no	no	no
Optional adapter used here	none	agents/openai.yaml	none	none

Full compatibility table: docs/ARCHITECTURE.md §10.

Validating a package

python3 scripts/validate-skill-metadata.py skills/local-code-review --containment-root .
python3 scripts/validate-skill-metadata.py skills/github-pr-review --containment-root .

Packaging-boundary guard tests live under tests/integration/packaging/ — see Development-Workflow.

---

Wiki Page Map

Page	What it covers
Home	Wiki entry point: what the two Skills are and where to go next.
Getting-Started	First steps to package and run either Skill.
Choosing-a-Review-Skill	How to decide between local-code-review and github-pr-review.
How-the-Review-Model-Works	Concept-level walkthrough of the review pipeline shared by both Skills.
Architecture-Overview	Component-level map of how the repository's pieces fit together.
Specialist-Depth-Review	When and how a review goes deeper than its base pass.
Local-Code-Review-Guide	Usage guide for reviewing local, not-yet-PR'd Git changes.
GitHub-PR-Review-Guide	Usage guide for reviewing an existing GitHub Pull Request.
Review-Context-and-Existing-Evidence	How optional requirements/context and prior review evidence are supplied.
Feature-Pages	Index of per-feature capability pages and their shared template.
Feature-Delta-Re-Review	How a re-review scopes itself to only what changed since the last pass.
Feature-GitHub-Publication-and-Authorization	What a PR review publishes to GitHub and under what authority.
Feature-Human-Style-Review-Output	The senior-engineer-voice prose summary output option.
Feature-Requirement-Coverage	How supplied requirements are checked and reported as covered or not.
Feature-Runtime-Validation-Evidence	How a review can execute commands or reproductions as evidence.
Severity-and-Decision-Model	The P0/P1/P2 severity levels and how the merge decision is derived.
Packaging-and-Portability	How the Skills go from source repository to a standalone archive.
Development-Workflow	Contributor guide for working on this repository itself.
Benchmark-Testing	Orientation to this repository's own review-quality benchmark pipeline.
Repository-Documentation-Map	Where each concern's canonical, authoritative source lives.
AI-Code-Review-Landscape	Neutral snapshot comparing this project against other AI code-review products.
FAQ	Short, practical answers to common questions.