Validation and Release Process
Use this process before sharing or publishing the skill package.
Local validation
Run the bundled validator from the skill root:
python scripts/validate-skill.pyThe validator checks:
- Agent Skills frontmatter shape, name rules, and description/compatibility length.
- YAML and JSON parseability.
- Template placeholder format and
parameters.example.yamlcoverage. - Bundle catalog completeness, dependency validity, resource references, manifest metadata, and catalog/manifest version parity.
- Review-mode defaults for response plans, scheduled tasks, and HTTP triggers.
- HTTP trigger disabled-by-default posture and bounded turn count.
- Custom-agent
allowed_skillscoverage for Azure SRE Agent YAML. - Basic secret-pattern scanning for accidental committed tokens or keys.
- Required hardening artifacts and local Markdown links.
Optional external validation
When available in the target environment, also run:
gh skill publish --dry-runIf skills-ref is installed, run:
skills-ref validate .Treat external validation failures as release blockers. Treat external warnings as review items unless the target host clearly does not support the rule.
Release checklist
Before releasing a new zip:
- Confirm
SKILL.mdstill routes to bundles instead of embedding deep reference content. - Confirm every catalog bundle has matching
versionin its localbundle.yaml. - Confirm all production-impacting templates default to
Review. - Confirm HTTP triggers default to
isEnabled: falseand use boundedmaxTurns. - Confirm write-capable agents have approval, rollback, and validation wording.
- Confirm connectors use placeholders only; never commit real tokens, API keys, bearer strings, client secrets, or storage keys.
- Confirm source-map links still represent the current authoritative documentation.
- Update
CHANGELOG.mdwith added, changed, fixed, and validation notes.
Versioning guidance
Use semantic versioning for the package:
- Patch: typo, example, or validator-only change that does not change behavior.
- Minor: new bundle, new reference, new validator rule, or backward-compatible operating-model improvement.
- Major: breaking package layout, bundle manifest schema change, or changed production safety posture.
Bundle versions may move independently, but catalog and bundle manifest versions must match.