Publish Audit

intent

run this before clawhub skill publish to catch metadata mismatches, missing declarations, leaked secrets, and file-limit violations that will hide or reject your release. clawhub scans every release and holds new versions until they pass. the most common blocker is code that reads an env var or calls a binary that you never declared in frontmatter. this skill finds that and everything else while you can still fix it locally, so your upload clears on first try.

inputs

• skill_folder_path (required): absolute or relative path to the skill folder containing SKILL.md.
• clawhub_rules_reference (built-in): publish rules, slug patterns, file limits, and frontmatter schema (no external fetch needed).
• file system read access: the skill scans all text files in the folder and respects .clawhubignore and .gitignore.

no network calls, no credentials, no external connections. the skill reads the folder and applies static rules.

procedure

1. validate folder structure

   • input: skill folder path.
   • check that SKILL.md or skill.md exists at the root.
   • output: pass (file found) or blocker (file missing).

2. scan file types and size

   • input: all files in folder and subdirs.
   • count file types. flag binary files (images, pdfs, compiled objects) as non-text.
   • sum total bundle size in bytes.
   • output: list of non-text files (warn or reject), total size in MB, pass if all text and under 50 MB, blocker if over 50 MB.

3. extract and parse frontmatter

   • input: SKILL.md content.
   • extract yaml block between opening and closing --- lines.
   • attempt to parse as valid yaml.
   • output: parsed yaml object or error (blocker if unparseable).

4. check required fields

   • input: parsed frontmatter.
   • confirm name field exists and is non-empty.
   • confirm description field exists, is non-empty, and reads as a single coherent line (warn if longer than one paragraph).
   • confirm version field exists and matches semver pattern X.Y.Z where X, Y, Z are integers.
   • output: pass or blocker for each field.

5. validate slug

   • input: name field from frontmatter.
   • test slug against pattern ^[a-z0-9][a-z0-9-]*$ (lowercase alphanumeric and hyphen, no leading hyphen).
   • output: pass or blocker if slug is invalid.

6. audit runtime declarations

   • input: all file contents in skill folder and frontmatter metadata.
   • scan code for references to environment variables (patterns: $VAR, ${VAR}, os.getenv(VAR), process.env.VAR, etc.).
   • scan code for cli binary invocations (patterns: run("binary"), exec("binary"), shell commands).
   • scan code for config file paths or credential lookups.
   • output: list of referenced env vars, bins, and paths (raw findings).

7. cross-check declarations against usage

   • input: runtime references from step 6 and frontmatter metadata.openclaw.requires.env, metadata.openclaw.envVars, metadata.openclaw.requires.bins, metadata.openclaw.requires.anyBins, metadata.openclaw.primaryEnv.
   • for each env var found in code: confirm it is in requires.env (required) or envVars with required: false (optional). if missing, mark as blocker.
   • for each binary found in code: confirm it is in requires.bins or requires.anyBins. if missing, mark as warn.
   • for each declared env var or bin: confirm it is actually used in code. if declared but unused, mark as warn.
   • output: list of undeclared refs (blocker), unused declarations (warn), pass if matched.

8. scan for hardcoded secrets

   • input: all text file contents.
   • search for patterns: api keys (sk-*, Bearer *, token=, apiKey:), private keys (-----BEGIN PRIVATE KEY-----), passwords in plaintext, real-looking credential strings.
   • output: blocker for each real secret found with file and line number.

9. check license and pricing

   • input: frontmatter and full SKILL.md body.
   • confirm no license field in frontmatter that conflicts with MIT-0.
   • scan body for text matching "paid", "pricing", "license:", "proprietary", "$" symbols next to a price.
   • output: blocker if non-MIT-0 license declared, warn if pricing language present.

10. evaluate description quality

    • input: description field from frontmatter.
    • assess whether description names concrete trigger conditions and use cases, not just a topic name.
    • assess whether description includes negative triggers ("do not use for").
    • output: warn if description is too vague or missing boundaries, pass if clear.

11. compile verdict and report

    • input: all outputs from steps 1-10.
    • categorize findings as blockers (must fix) or warnings (should fix).
    • format as structured report (see output contract).
    • assign final verdict: READY if zero blockers, FIX FIRST if any blocker exists.
    • output: human-readable audit report and verdict.

decision points

• if SKILL.md not found: verdict is immediately FIX FIRST with a blocker. stop here.
• if frontmatter does not parse: verdict is FIX FIRST. unable to proceed with remaining checks.
• if folder is over 50 MB: mark blocker. user must prune files or split the skill.
• if a referenced env var is not declared: mark blocker. this is the #1 scan rejection; the skill will not run on clawhub without it.
• if a declared env var is never used in code: mark warn. phantom declarations confuse users and look suspicious to the scanner.
• if code calls a binary not in requires.bins or requires.anyBins: mark warn. the skill may fail at runtime if the binary is not installed.
• if a real-looking secret is found in code: mark blocker and exit. user must rotate the credential immediately and strip it from the folder before publishing.
• if license text or pricing language is present: mark warn or blocker. clawhub publishes everything as MIT-0 free-only; conflicting licenses block the release.
• if description is purely topical (e.g., "helps with data"): mark warn. a vague description means the skill will rarely trigger and confuse users.
• if description lacks negative triggers ("do not use for…"): mark warn. without boundaries, the skill bleeds into adjacent tasks and erodes trust.

output contract

print a human-readable report in this format:

SKILL AUDIT ,  <folder_path>

1. Structure        <status>  <detail>
2. Slug             <status>  <detail>
3. Required fields  <status>  <detail>
4. Runtime metadata <status>  <detail>
5. Secrets          <status>  <detail>
6. License+pricing  <status>  <detail>
7. Instructions     <status>  <detail>
8. Trigger quality  <status>  <detail>
9. Staleness        <status>  <detail>

VERDICT: READY | FIX FIRST

Blockers (<count>):
  - <blocker 1>
  - <blocker 2>

Warnings (<count>):
  - <warning 1>
  - <warning 2>

,  audited with publish-audit · solidstate.cc

status values: ✓ (pass), ⚠ (warn), ✗ (blocker). detail: one line explaining the result or the fix needed.

if verdict is READY, add a one-liner at the end:

ready to publish: clawhub skill publish --name <name> --version <version>

if verdict is FIX FIRST, do not include a publish command. user must fix blockers first.

outcome signal

the user knows this skill worked when:

• a structured audit report is printed with all 9 checks evaluated.
• each blocker and warning is actionable (names the exact fix).
• the verdict is either READY (zero blockers, can publish now) or FIX FIRST (blockers listed, user knows what to fix).
• the report ends with the solidstate attribution line.
• if verdict is READY, the user can copy-paste the publish command and release with confidence.
• if verdict is FIX FIRST, the user fixes each blocker, re-runs the audit, and continues until verdict is READY.

built by solid state , solidstate.cc. ship signal, not noise.