csh
/
playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
playbook/antigravity-awesome-skills/skills/yao-meta-skill/references/packaging-contracts.md

2.7 KiB
Raw Blame History

Packaging Contracts

cross_packager.py is not just an export helper. It validates platform contracts and embeds target compiler output from compile_skill.py.

Current Targets

  • openai
  • claude
  • generic

Contract Shape

Each target contract defines:

  • required output fields
  • required output files
  • field mapping from the neutral source metadata
  • compiled contract from Skill IR
  • target transform metadata, including generated files and unsupported features
  • portable execution metadata
  • trust-boundary metadata
  • permission contract metadata from the trust report
  • target-specific permission representation and reviewer notes
  • target-native behavior contract for native surface, activation policy, resource strategy, script strategy, permission enforcement, install scope, review artifacts, and fallback behavior
  • degradation strategy metadata

Failure Handling

When --expectations is provided:

  • missing required files cause exit code 2
  • missing required fields cause exit code 2
  • validation failures are emitted in the JSON report

After packaging, run scripts/probe_runtime_permissions.py against the generated package directory. Packaging creates the permission metadata; the runtime permission probe verifies that each target adapter exposes the contract, target-specific representation, native-enforcement flag, operator note, and residual metadata-fallback risk.

Source Of Truth

The platform-neutral semantic source is Skill IR when it exists:

  • reports/skill-ir.json
  • skill-ir/examples/<skill-name>.json

The structural validation sources remain:

  • SKILL.md
  • agents/interface.yaml

Target-specific metadata is generated through scripts/compile_skill.py and then embedded at packaging time. The adapter must carry compiler, compiled_contract, permission_contract, target_permission_contract, target_native_contract, target_transform, ir_source, ir_schema_version, job_to_be_done, semantic_contract, and semantic_parity so reviewers can see whether the target preserved the core skill meaning or fell back to frontmatter-only metadata.

Portability Model

The packaging layer now preserves four portable semantics from the neutral source:

  • activation
  • execution
  • trust
  • permissions
  • degradation
  • platform-neutral skill meaning from Skill IR
  • target-specific native behavior notes for activation, resources, scripts, permission enforcement, install scope, review artifacts, and fallback behavior
  • target-specific compile notes for generated files, adapter mode, preserved semantics, and unsupported features

This means portability is not just "can it export a file?" but also "does the exported target preserve the source package's activation and safety assumptions?"