V1

Public Release Review

Pre-publication quality gate for public-facing skills. Verifies every skill headed to the public repository is safe, well-documented, properly versioned, and understandable to any downloader.

This is not a generic push skill. It runs specifically when a skill is about to be publicly released or updated, and ensures the public-facing materials are complete and high quality.

When this skill runs

Automatically (via vault-push-guardian Phase 2F):

• A public_safe: true skill is modified in a pre-push diff
• A skill transitions from public_safe: false to public_safe: true
• A skill is reorganized or optimized and remains public-facing

Explicitly (user-invoked):

• Preparing a skill for first public release
• Before posting or reposting a skill publicly
• After meaningful updates to a public skill's documentation, version, or behavior
• During weekly vault maintenance when public skills changed

Trigger detection

Before running full review, determine whether this skill should run:

# Check which skills changed in the diff
git diff --cached --name-only | grep 'skills/' | grep -v '_archive\|_templates\|_registry\|_obsolete'

For each changed skill path, check its public_safe status:

cat skills/<category>/<skill-name>/metadata.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('public_safe', False))"

Run review if: public_safe: true OR the skill is being set to public_safe: true in this diff.

Skip silently if: public_safe: false, skill is in _archive, or no public-facing skills changed.

Phase 1: Public safety check

Scan the skill's SKILL.md, README.md, CURRENT.md, metadata.json, and CHANGELOG.md for disallowed content.

Block publication if ANY of the following appear:

# Personal identifiers
grep -rE '/Users/[a-zA-Z]{2,20}/' skills/<category>/<skill-name>/

# API keys, tokens, secrets
grep -rE '(sk-|ghp_|gho_|ghs_|xai-|ANT[A-Z0-9]{20,}|Bearer [a-zA-Z0-9_\-\.]{20,})' skills/<category>/<skill-name>/

# Generic credential assignments
grep -riE '(api[_-]?key|api[_-]?secret|password|secret|private[_-]?key|access[_-]?token)\s*[=:]\s*['"'"'"][^'"'"'"]{8,}['"'"'"]' skills/<category>/<skill-name>/

# Private repo URLs or internal endpoints
grep -rE 'github\.com/[a-zA-Z0-9_-]+/(private|internal|personal)' skills/<category>/<skill-name>/

# Personal notes markers
grep -rE '(NOTE TO SELF|personal:|travel:|my schedule|private:)' skills/<category>/<skill-name>/

Safe patterns (do not flag):

• ~/path/to/... — relative paths are fine
• /path/to/project — generic placeholder paths are fine
• /Users/{user}/ — placeholder form is fine
• Example credentials with obvious placeholder values (e.g., YOUR_API_KEY, <token>)

If blocked: stop and output the BLOCKED block (see Output Rules). Do not proceed.

Phase 2: README quality check

Read README.md for the skill under review.

Required sections — fail if ANY are missing or clearly inadequate:

Quality bar:

• A person downloading this skill for the first time should understand it in 30 seconds
• "What it does" must not be vague (e.g., "does stuff" or just the skill name repeated)
• If the skill superseded an older skill, that relationship must be stated

If a required section is missing: flag it — do not block publication, but require fix before next push of this skill.

Phase 3: Version visibility check

Verify the current version is consistent and visible across all files:

# Extract versions from each file
cat skills/<category>/<skill-name>/metadata.json | python3 -c "import sys,json; d=json.load(sys.stdin); print('metadata.json version:', d.get('version'))"
grep -m1 'Version' skills/<category>/<skill-name>/README.md
grep -m1 'Version\|version' skills/<category>/<skill-name>/CURRENT.md

Pass condition: All three sources agree on the same version string (e.g., v1, v2.1).

Fail condition: Version missing from README or CURRENT.md, or versions disagree across files.

Phase 4: CHANGELOG quality check

Read CHANGELOG.md. Apply these checks:

Must have: At least one entry if the skill has been updated since initial creation.

Entry quality — reject entries that are only noise:

• "small wording tweak" alone → too trivial for public changelog
• "minor formatting fix" alone → too trivial
• "temporary draft adjustment" → should never appear in public changelog

Accept entries that reflect:

• Added capability or behavior
• Improved documentation quality
• Security or safety improvements
• Reorganization affecting public use
• Version or category changes

If CHANGELOG is empty on a non-v1 skill: flag as missing. If CHANGELOG entries are all trivial noise: flag for cleanup.

Phase 5: Public update notes assessment

Determine whether meaningful public-facing changes occurred since the last public version.

Check last released version:

ls skills/<category>/<skill-name>/versions/ | sort -V | tail -1

Compare current SKILL.md against last version:

diff skills/<category>/<skill-name>/versions/<last-version>/SKILL.md \
     skills/<category>/<skill-name>/SKILL.md | head -60

Classify the diff:

If update notes are needed, generate a concise summary following release significance rules:

• PATCH (vX.Y.Z → vX.Y.Z+1): One-line note if public behavior or clarity changed
• MINOR (vX.Y → vX.Y+1): 2-4 lines covering new or improved capabilities
• MAJOR (vX → vX+1): Short paragraph covering the larger change

Good examples:

• v1.1 — improved trigger detection logic and added parallel agent support
• v2.0 — restructured as standalone skill; now integrates directly into vault-push-guardian

Bad examples (do not write):

• updated line 12 wording
• minor edit
• fixed typo in section 3

If update notes are needed but missing from README and CHANGELOG, write them now and apply to both files.

Phase 6: Public download readiness check

Verify the skill folder is clean and understandable for a public downloader:

ls skills/<category>/<skill-name>/

Required files:

• SKILL.md — main skill instructions
• README.md — public-facing description
• CURRENT.md — current state snapshot
• metadata.json — machine-readable metadata
• CHANGELOG.md — version history

Check for junk:

• No .DS_Store, *.tmp, *.bak files
• No draft files (e.g., SKILL-DRAFT.md, notes-temp.md)
• No files with names that suggest private or incomplete state

File naming: All filenames should be clear and purposeful. No ambiguous names.

Decision and output

If ALL checks pass:

Run silently. No output.

If issues found:

Output one concise block per skill:

PUBLIC RELEASE BLOCKED — skills/<category>/<skill-name>
Issue: [specific problem]
File: [file with problem]
Fix: [exact action needed]

Multiple issues for the same skill:

PUBLIC RELEASE NEEDS FIXES — skills/<category>/<skill-name>
1. [Issue + fix]
2. [Issue + fix]

If update notes were auto-generated:

One-line note only:

Updated public notes — skills/<category>/<skill-name>/README.md + CHANGELOG.md

Output rules

Silent unless:

• Public safety fails → BLOCKED, stop everything
• Required README sections are missing → list gaps
• Version mismatch across files → flag
• CHANGELOG missing or all-noise on updated skill → flag
• Update notes were auto-generated and applied → one-line note

Never output:

• "Checking..." progress messages
• Confirmation that passing files passed
• Verbose grep output
• Internal diff details unless directly relevant to a reported issue

Parallel execution (for full vault scan)

When reviewing multiple skills at once (e.g., weekly maintenance):

• Agent A: Public safety scan (Phase 1) across all changed public skills
• Agent B: Documentation quality review (Phases 2–3) across all changed public skills
• Agent C: Changelog and update notes (Phases 4–5) across all changed public skills

Merge results. Block push on any BLOCKED result. Apply update notes from Agent C before commit.

Integration with vault-push-guardian

This skill is called during vault-push-guardian Phase 2F, after Phase 2E completes.

Phase 2F trigger condition: Any file in git diff --cached --name-only matches a skill path where public_safe: true.

Phase 2F behavior:

1. Identify all public-facing skills in the diff
2. Run public-release-review on each
3. If any are BLOCKED → block the push (same as Phase 2 blocking behavior)
4. If update notes were generated → stage those files before commit
5. If fixes needed but not blocking → include in commit message as review: public docs refresh

Commit message prefixes:

• Clean push: no change to commit message
• Update notes applied: append (public docs refreshed)
• Blocking issue: PUSH BLOCKED — see output above

Release significance logic

Use this table when deciding update note depth:

When in doubt: if a public downloader would notice or benefit from knowing, include it. If they wouldn't care, skip it.