Skill Release Audit

skill-release-audit

• Version: 1.0.4
• License: MIT
• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/build-better-skills
• Part of: build-better-skills suite — see Stages for the lifecycle map.

A six-module static inspector that catches mechanical problems machines can verify — broken Python syntax, undeclared env vars, files written inside the skill dir that would be lost on update, missing README/LICENSE for GitHub targets, mismatched docs and scripts. Pairs with glic-check which does cognitive UGLIC review; together they cover both layers (see [Part of build-better-skills](#part-of-build-better-skills)).

Prints a structured ✅/⚠️/❌ report per module with actionable fixes. Does not auto-fix. All fixes require user confirmation.

---

Agent Behavior Rules (must-read)

This skill is an Auditor, not a Fixer.

After running the check, the agent must follow these rules strictly:

1. Show the full report first — every module result, every warning / error

with its specific description.

1. Suggest fixes per finding, but only as suggestions, not actions.
2. Wait for explicit user confirmation before touching any file.
3. Never modify SKILL.md, scripts/, references/, or any other file without

confirmation.

1. Never delete files, even ones that look like leftovers — always ask first.

Correct output template:

📋 Check report: 
[full output of healthcheck.py]

---
Issues found. Please confirm what to do:

✅ Can be ignored (false positives):
- Module 1: cache.json path warning — SKILL.md mentions it as descriptive text,
  not a file reference.

⚠️ Suggested fixes (awaiting your confirmation):
1. Module 3: auto_update.py _log() missing try/except — suggest wrapping.
2. Module 2: guide.py not listed in SKILL.md's module table — suggest adding.

Tell me which to fix and which to ignore. I'll act after you confirm.

---

Usage

# Full check — report only, does NOT modify your environment (default)
python scripts/healthcheck.py 

# Opt in to auto pip-install missing Python deps (off by default)
python scripts/healthcheck.py  --auto-install

# Tune per-package install timeout (only with --auto-install)
python scripts/healthcheck.py  --auto-install --install-timeout 120

# Validate against a specific publishing target (tunes checks, does NOT publish)
python scripts/healthcheck.py  --target clawhub

# Report output language: zh or en (default: auto-detected from $LC_ALL / $LANG)
python scripts/healthcheck.py  --lang en

# Run specific modules only (e.g. deps + docs)
python scripts/healthcheck.py  --modules 5,6

> Default behavior is report only, do not install — an auditor should not > mutate the user's environment. Missing required deps are reported as ERROR; > with --auto-install, install failures are reported as WARN (usually > network/registry issues, not skill bugs).

Publishing target (--target)

Different registries have different rules. --target tunes which checks fire and at what severity — it does not publish.

| target | Use case | Notes | |--------|----------|-------| | generic (default) | Cross-registry minimum | Loosest, smallest common set | | clawhub | clawhub.com | name+description required, strict slug, 50MB cap, declaration-vs-code consistency | | anthropic | Anthropic-compatible base spec | name≤64 / description≤1024, body recommended .json there. See [references/hub-specs.md`](references/hub-specs.md) for per-registry specifications encoded by these profiles.

Report language

Default: auto-detected from $LC_ALL / $LC_MESSAGES / $LANG. Falls back to zh (legacy default). Currently supported: zh / en.

• CLI: --lang zh / --lang en
• Env: SKILL_AUDIT_LANG=en (lower priority than --lang)

All user-facing text is centralized in scripts/i18n.py as a bilingual key-table — add a new check by adding one zh/en entry; do not hardcode strings in module files.

Exit codes: 0 = no errors (may have warnings), 1 = errors found, 2 = invalid input.

The six modules

| Module | Checks | Script | |--------|--------|--------| | 1. Syntax & logic | Python AST parse, Bash -n syntax check, internal reference paths, leftover TODO/FIXME | scripts/check_logic.py | | 2. Feature coverage | scripts / references mentioned in SKILL.md, stub-file detection | scripts/check_features.py | | 3. Edge cases | try/except coverage, HTTP timeout, response-status handling, Bash set -e | scripts/check_edges.py | | 4. Data safety | Files written inside the skill dir (lost on update) | scripts/check_data_safety.py | | 5. Dependencies | Python / Node / Bash deps, optional --auto-install, declaration-vs-code env check | scripts/check_deps.py | | 6. Documentation | description quality, frontmatter discipline, slug rules, target-specific required files (README / LICENSE) | scripts/check_docs.py |

Data safety hint

Skill directories are overwritten on update. All persistent data must live outside the skill dir. The auditor probes the runtime environment (OpenClaw / Claude Code / Codex / plain checkout) and suggests a portable path:

from pathlib import Path
DATA_DIR = Path.home() / ".skill-data" / ""   # example, auto-tuned

See references/safe-paths.md for the full resolution order.

Declaration vs code env check

Mirrors registry-side security analysis: if your code reads an env var (os.environ["X"], os.getenv(...), process.env.X) that isn't declared in frontmatter under metadata.openclaw.requires.env / primaryEnv / envVars, the auditor flags a metadata mismatch (severity is profile-driven). This catches the most common cause of post-publish runtime failures.

Dependency declaration convention

In SKILL.md body, add a dependency section:

## Dependencies

Auto-installed on first use: requests, pyyaml

System commands (install manually): jq (`brew install jq`)

See references/dep-patterns.md.

Dependencies

Core uses Python 3.8+ standard library only — no external installs needed.

Optional enhancement: pyyaml (auto-detected). With PyYAML, frontmatter parsing handles multi-line / list / nested fields strictly. Without it, a tolerant built-in parser handles inline JSON values (e.g. metadata: {"key": "value"}) so the same checks still work — no functionality loss.

Part of build-better-skills

This skill belongs to the build-better-skills suite. For the full lifecycle map (Install → Audit → Release → Testing → Sediment), all sibling skills, and their current status, see the Stages table on the suite repo home — kept as the single source of truth (this file does not duplicate it).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Songhonglei
• Source: Songhonglei/build-better-skills
• License: MIT

Install and usage instructions live in the source repository linked above.