ClawHub Release Auditor#

Run a strict preflight before any publish. Prefer stopping with a precise explanation over guessing. Treat repeated versions as a signal that the workflow needs diagnosis, not just another upload.

Workflow#

1. Preflight
   • Run python3 scripts/preflight.py <skill-dir>.
   • Fix all hard errors before continuing.
   • Read warnings carefully; they often explain why a skill ends up suspicious.
2. Package locally
   • Run python3 ~/project/openclaw/skills/skill-creator/scripts/package_skill.py <skill-dir> [output-dir].
   • If packaging fails, stop and explain the exact validation error.
3. Confirm before publish
   • Show the skill path, intended version, and any remaining warnings.
   • Do not publish without explicit user confirmation.
4. Publish
   • Publish from the skill folder, not the .skill archive.
   • After publish, record the exact version that was attempted.
5. Verify post-publish state
   • Run python3 scripts/verify_publish.py <skill-slug> --expected-version <version>.
   • If latest/version visibility is inconsistent, say so clearly.
   • If scan results matter, check the web page separately and explain whether the issue is pending, version mismatch, or a likely metadata/code mismatch.

What to check during preflight#

• Frontmatter only uses supported keys.
• name and description are present and sane.
• Placeholder text is not leaking into examples.
• Declared metadata.openclaw.requires roughly matches real script usage.
• Homepage/source metadata exists when possible.
• Publish path points to the skill directory, not the packaged archive.
• Local package validation passes before any publish attempt.

Common failure patterns#

Frontmatter mismatch#

If validation complains about unsupported keys, trust the validator. Do not invent alternate formats from memory.

Metadata drift#

If scripts use env vars or binaries that the skill does not declare, expect suspicious scan results. Fix the declaration or the code.

Placeholder leakage#

If docs contain example paths like /path/to/..., make sure they are clearly examples and not presented as real files.

Repeated publish loops#

If many versions are being published quickly, pause and diagnose:

• Did packaging actually succeed?
• Did latest move?
• Is scan still reading an older version?
• Is the same metadata mismatch still present?

Scripts#

scripts/preflight.py#

Checks a skill directory for:

• frontmatter problems
• placeholder text
• likely undeclared env vars and binaries
• external execution hints
• package validation failures
• a simple verdict: do-not-publish, review-before-publish, or ready-to-package

scripts/verify_publish.py#

Checks published version state with clawhub inspect and compares it to an expected version.

scripts/analyze_history.py#

Inspects recent version history for a public skill and groups releases into rough categories such as docs, metadata, bugfix, and feature work. Use it to study repeated publish loops and sharpen the skill's heuristics.

scripts/failure_buckets.py#

Classifies likely publish problems into practical buckets such as frontmatter-invalid, package-validation-failed, latest-not-updated, or no-hard-failure-detected.

scripts/release_worthiness.py#

Compares a local skill directory against the latest published version and flags when there is no material diff. Use it to avoid unnecessary republish loops.

Publishing tips#

SKILL.md body must have substantial content#

ClawHub checks for "Skill content is too thin or templated." This evaluates the SKILL.md body text (markdown below frontmatter), not just the description field.

Why this matters:

• The description field is only used for UI/search summaries
• The SKILL.md body is what gets embedded and evaluated for the thin-content check
• If SKILL.md has only frontmatter and no body text, it will fail even with a perfect description

How to avoid:

• Always include substantive body content in SKILL.md (at least 300-500 words of meaningful guidance)
• Include real workflow guidance, usage examples, and operational notes in the body
• The more comprehensive the SKILL.md body, the less likely it triggers "templated" detection

Other common pitfalls#

• homepage field: Include a valid URL to avoid warnings
• Empty directories: Remove any empty scripts/, references/, or other directories before packaging
• Symlinks: These are rejected by the packager and cause failures

References#

• Read references/checklist.md for the release checklist.
• Read references/research-notes.md when designing heuristics for repeated publish loops and common failure modes.
• If the skill format or server behavior is unclear, read the official ClawHub skill format docs before guessing. Prefer current docs plus validator output over old habits.