clawhub-skill-creator

What this skill does

# clawhub-skill-creator

Scaffold and publish ClawhHub-ready OpenClaw skills. Follow every rule below. Do not skip sections. Do not invent conventions not listed here.

Ask the user for the **skill name** and **purpose** if not already provided, then generate the files.

---

## Structure

Generate two files only — no README.md, no CHANGELOG.md, no auxiliary docs:

```
[skill-name]/
├── SKILL.md       (required)
└── _meta.json     (required)
```

---

## Understanding the ClawhHub Scanner

The scanner is the gatekeeper between publishing and availability. Know how it works before writing a single line:

**1. The description summary is the ONLY thing the scanner trusts at the registry level.**
`_meta.json` fields (`requiredConfigPaths`, `primaryCredential`, `requires`) are stored but NOT surfaced in the registry API. The scanner cannot read them. Everything the scanner needs to verify must be in the description — and in the FIRST ~160 characters, because that is where the registry truncates the summary.

**2. The scanner is iterative — it reveals one layer at a time.**
Each fix exposes the next issue. It will not give you all problems at once. Expect multiple publish cycles. This is by design — it is a progressive trust gate.

**3. The scanner cannot verify nested content.**
A worker script embedded inside a here-string inside a code block will be marked as truncated and unverifiable. All content the scanner needs to read must be flat and standalone.

**4. The scanner is semantic, not keyword-based.**
It understands the difference between what is logged vs transmitted, always:true vs always:false, handle vs userId, and required vs optional credentials. It catches logical inconsistencies, not just missing keywords.

**5. The scanner is conservative by default.**
It blocks and warns rather than approves. Every publish triggers a new scan. Do not publish until the checklist passes — each rejected version counts against the skill's history.

---

## Known OpenClaw Parser Gotchas (learned from real failures)

These will silently break skill detection — no error, skill just disappears from `openclaw skills list`:

- **Missing closing `---` in frontmatter**: If the frontmatter block is not closed with `---`, OpenClaw silently fails to parse the skill entirely. Always verify the closing delimiter exists.

- **`openclaw` in `metadata.openclaw.requires.bins`**: OpenClaw does not recognize itself as a bin to check and silently hides the skill. Never put `openclaw` in bins. Use `anyBins: ["powershell","pwsh"]` for OS gating — the openclaw runtime is implied.

- **Skills in `~/.openclaw/skills/` not auto-detected**: OpenClaw scans `<workspace>/skills/` by default. For skills in `~/.openclaw/skills/`, add `skills.load.extraDirs: ["~/.openclaw/skills"]` to `openclaw.json`. Also add `skills.entries.<name>.enabled: true` for each skill.

- **`clawhub install` path**: By default installs into `./skills` (cwd) or `<workspace>/skills`. Always pass `--workdir` explicitly or install directly to `~/.openclaw/skills/` and add extraDirs.

- **Encoding**: Always write SKILL.md with `[System.Text.UTF8Encoding]::new($false)` (no BOM). BOM or encoding artifacts in frontmatter break the YAML parser silently.

---

## ClawhHub Scanner Criteria

Address all five explicitly — in the description first, then in the body.

### 1. Purpose & Capability
- State exactly what APIs/services are called (e.g. "graph.facebook.com only")
- State what the skill does NOT do ("no data forwarded to third parties")
- If background process: state exactly what is READ, what is TRANSMITTED, what is LOGGED
- If long-lived tokens: state rotation guidance + immediate rotation if host is compromised
- If setup-only secrets (e.g. APP_SECRET): state "delete afterward" explicitly

### 2. Instruction Scope
- Required binaries and credentials at the START of the description (fits in ~160-char summary)
- Required CLIs declared in BOTH places:
  - `metadata.openclaw.requires.anyBins` in SKILL.md frontmatter (OpenClaw load-time gating)
  - `_meta.json requires.anyBinaries` (registry metadata)
- SKILL.md body and _meta.json must match — no features in one but not the other
- OS restriction in description if PowerShell-specific
- Least-privilege note: state "grant token minimal permissions only"

### 3. Install Mechanism
- No external script downloads at runtime — all worker code inline in SKILL.md
- Worker scripts extracted from SKILL.md at runtime, not constructed from string literals

### 4. Credentials
- All credential requirements named in the description (file path + field names)
- Distinguish required vs optional fields (e.g. APP_SECRET: setup only, delete afterward)
- No token literals in any script — credentials always read fresh from disk at runtime
- All runtime files permission-restricted (icacls/chmod 600): config, worker, log, pid, state
- Worker stored in ~/.config/[skill]/worker.ps1 — never in system temp
- Logs contain metadata only — no secrets, no message content
- Long-lived tokens: include rotation guidance and immediate-rotation-if-compromised note

### 5. Persistence & Privilege
- `always:true` is forbidden in community skills — high blast radius, scanner flags it
- Background processes opt-in only — never autonomous
- Declare in _meta.json persistence: type, code, optional:true, description
- Description must state: what is read, transmitted, logged, and to where
- Worker content must be fully readable by scanner — own dedicated section, plain code block
- Pid file cleaned up on stop

---

## File Specifications

### SKILL.md Frontmatter

```yaml
---
name: [skill-name]
description: "[What it does in plain English — action-focused, no 'AI' prefix]. Requires: [binaries]. Reads [credentials file] ([FIELDS]). [Setup-only secrets: delete afterward.] [Long-lived tokens: rotate periodically; rotate immediately if host compromised.] Grant token minimal permissions only. No data forwarded to third parties; all calls go to [domain] only."
metadata: {"openclaw":{"emoji":"[icon]","requires":{"anyBins":["powershell","pwsh"]}}}
---
```

Rules:
- Description is a QUOTED single-line string
- **Lead with a value hook** — describe what the skill does in plain, action-focused language (e.g. "Facebook Page manager: post, schedule, reply & get insights"). This is what users searching ClawhHub will read first. Do NOT start with "AI". Do NOT start with "Requires:".
- **Technical requirements follow the hook** — after the value hook, include: `Requires: [binaries]. Reads [credentials file] ([FIELDS]).`
- Keep the combined hook + requirements within ~160 characters so both appear in the registry summary
- NEVER put `openclaw` in `bins` or `anyBins` — it silently hides the skill
- Do NOT use `always:true` — scanner flags it as high blast radius
- Do NOT add any other frontmatter fields (no runtime, clawdbot, credentials blocks)
- Frontmatter MUST end with a closing `---` line — verify it exists before publishing

**Good description example:**
```
"Facebook Page manager: post, schedule, reply & get insights. Requires: powershell/pwsh. Reads ~/.config/fb-page/credentials.json (FB_PAGE_TOKEN, FB_PAGE_ID). FB_APP_SECRET for one-time setup only — delete afterward. Long-lived token; rotate periodically and immediately if host is compromised. Grant minimal permissions only. No data forwarded to third parties; all calls go to graph.facebook.com only."
```

**Bad description example (do not do this):**
```
"Requires: powershell/pwsh. Reads ~/.config/fb-page/credentials.json (FB_PAGE_TOKEN, FB_PAGE_ID). Interact with any Facebook Page feature via the Meta Graph API..."
```
The bad example leads with dry technical info — users scanning ClawhHub skip it.

### _meta.json

> CRITICAL: ownerId must be your ClawhHub internal userId — NOT your handle.
> Get it: `clawhub inspect <one-of-your-skills> --json`
> Look for `owner.userId` (e.g. "kn7824yf4srh3akes6axhmqf5n81q7dh") — NOT "seph1709"
> Using the handle causes registry owner ver