skill-release-audit

• Version: 1.2.0
• 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).

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.
2. Suggest fixes per finding, but only as suggestions, not actions.
3. Wait for explicit user confirmation before touching any file.
4. Never modify SKILL.md, scripts/, references/, or any other file without
   confirmation.
5. Never delete files, even ones that look like leftovers — always ask first.

Correct output template:

📋 Check report: <skill-name>
[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 <path/to/skill-dir>

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

# Tune per-package install timeout (only with --auto-install)
python scripts/healthcheck.py <path/to/skill-dir> --auto-install --install-timeout 120

# Validate against a specific publishing target (tunes checks, does NOT publish)
python scripts/healthcheck.py <path/to/skill-dir> --target clawhub
python scripts/healthcheck.py <path/to/skill-dir> --format json

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

# Run specific modules only (e.g. deps + docs)
python scripts/healthcheck.py <path/to/skill-dir> --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.

Profiles live in profiles/ as JSON; add your own by dropping a new
<name>.json there.

Env-var check severity is configured per finding code via each profile's
env_severity key (v1.1 governance): ENV_REQUIRED_UNDECLARED /
ENV_OPTIONAL_OVERRIDE / ENV_RUNTIME_INJECTED / ENV_AMBIENT /
ENV_TEST_ONLY / ENV_REVIEW_REQUIRED — each maps to WARN / INFO / OFF.
Platform env contracts (runtime-injected / ambient lists) live in
config/env_contracts.json. See references/hub-specs.md
for per-registry specifications encoded by these profiles.

JS env data-flow tracking (v1.2): for JS/TS scripts the auditor tracks
environment-object alias propagation — const environment = process.env,
fn(process.env) parameter binding, Zod schema.parse(environment) /
safeParse({...environment}) results, and config-loader return values
(const config = loadConfig(process.env)). Member accesses on those aliases /
parse results count as indirect uses: they only affect the reverse check
(a declared var is no longer misjudged ENV_DECLARED_UNUSED) and are filed
under the ENV_DECLARED_INDIRECT class — silent in the console report by
default, with hit paths preserved in JSON evidence. Indirect uses never
soften the forward classification (required / optional). Vars whose
propagation cannot be confirmed still report ENV_DECLARED_UNUSED.

Module-1 ref classification (v1.2.1): paths referenced in SKILL.md are
split into package-internal refs (validated as before) and runtime-external
refs (~/..., $HOME/..., absolute paths incl. Windows drive letters) —
the latter resolve in the user's environment at runtime, so existence is
not a package-completeness problem: resolvable paths are skipped silently,
unresolvable ones emit INFO (never WARN).

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

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" / "<skill-name>"   # 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).