# Skill Release Audit

> >

- **Type:** Skill
- **Install:** `agentstack add skill-songhonglei-build-better-skills-skill-release-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Songhonglei](https://agentstack.voostack.com/s/songhonglei)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Songhonglei](https://github.com/Songhonglei)
- **Source:** https://github.com/Songhonglei/build-better-skills/tree/main/skills/skill-release-audit

## Install

```sh
agentstack add skill-songhonglei-build-better-skills-skill-release-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# skill-release-audit

- **Version**: 1.0.4
- **License**: MIT
- **Author**: Evan Song · [github.com/Songhonglei](https://github.com/Songhonglei)
- **Repository**: https://github.com/Songhonglei/build-better-skills
- **Part of**: [`build-better-skills`](https://github.com/Songhonglei/build-better-skills) suite — see [Stages](https://github.com/Songhonglei/build-better-skills#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`](https://github.com/Songhonglei/build-better-skills/tree/main/skills/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.
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: 
[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

```bash
# 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:

```python
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:

```markdown
## 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`](https://github.com/Songhonglei/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**](https://github.com/Songhonglei/build-better-skills#stages) 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](https://github.com/Songhonglei)
- **Source:** [Songhonglei/build-better-skills](https://github.com/Songhonglei/build-better-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-songhonglei-build-better-skills-skill-release-audit
- Seller: https://agentstack.voostack.com/s/songhonglei
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.