---

name: openclaw-skill-conformance description: > Validate and fix SKILL.md files against the OpenClaw standard format. USE WHEN: User wants to publish a skill to ClawMart, is writing a new SKILL.md, wants to check if an existing skill is correctly formatted, or asks "does this skill conform?", "check my skill format", "validate SKILL.md", "fix my skill format". DON'T USE WHEN: User wants to audit for security (use skill-inspector). Not for reviewing skill content quality — this is purely structural/format conformance. OUTPUTS: Conformance report + corrected SKILL.md if fixes are needed. version: 1.1.0 author: SpookyJuice tags: [skill-authoring, conformance, validation, openclaw, clawmart] price: 0

OpenClaw Skill Conformance

Version: 1.1.0 Price: Free Type: Skill

Description

Validates that a SKILL.md file meets the OpenClaw standard format before publishing to ClawMart. Catches structural issues, missing required fields, and format violations that would degrade how the skill triggers in agent context.

OpenClaw uses the SKILL.md frontmatter and body structure to determine when and how to invoke a skill. Malformed frontmatter means the skill may never trigger. Weak description fields mean the skill triggers at the wrong time or not at all. Missing USE WHEN / DON'T USE WHEN blocks cause skill collisions. This validator catches all of that before you publish.

Prerequisites

• An OpenClaw installation with a skills/ directory
• At least one SKILL.md file to validate (local path or pasted content)
• No API keys or external services required — fully offline

Setup

1. Copy SKILL.md into your OpenClaw skills directory (e.g. skills/openclaw-skill-conformance/SKILL.md)
2. Reload OpenClaw
3. Confirm the skill is active with: "Is OpenClaw Skill Conformance loaded?"

Commands

• "Validate my SKILL.md"
• "Check if this skill conforms to OpenClaw standards"
• "Does my skill format look right?"
• "Fix my SKILL.md before I publish"
• "Run conformance check on [skill-name]"
• "Is [skill-name] formatted correctly for ClawMart?"
• "Lint my skill"

The OpenClaw SKILL.md Standard

Required Frontmatter Fields

---
name: slug-style-name          # required — lowercase, hyphenated, unique
description: >                 # required — multiline preferred for rich trigger matching
  What the skill does.
  USE WHEN: [trigger conditions and keywords]
  DON'T USE WHEN: [anti-triggers — what NOT to use this skill for]
  OUTPUTS: [what the skill produces]
version: 1.1.0                 # required — semver
---

Optional Frontmatter Fields

author: YourName               # recommended
slug: same-as-name             # optional, defaults to name
tags: [tag1, tag2]             # optional — improves searchability
price: 0                       # optional — 0 for free, dollar amount for paid
repo: https://github.com/...   # optional — source repo link

Required Body Sections

The markdown body must include at minimum:

1. H1 title — Human-readable name (can differ from frontmatter name)
2. Description block — What the skill does and why it exists
3. Commands section — Natural language phrases that trigger this skill
4. Workflow section — Step-by-step instructions for the agent to follow

Recommended Body Sections

• Prerequisites — What must be set up before the skill works
• Setup — Installation/configuration steps
• Output Format — What the skill produces, with examples
• Guardrails — What the skill must never do

Conformance Rules

CRITICAL (blocks publish)

| Rule | Description | |------|-------------| | name required | Frontmatter must have a name field | | description required | Frontmatter must have a description field | | version required | Frontmatter must have version in semver format | | name format | Must be lowercase, hyphen-separated, no spaces or special chars | | H1 required | Body must have exactly one H1 (#) heading | | No YAML parse errors | Frontmatter must be valid YAML | | Minimum body length | Body must be at least 200 characters (excluding frontmatter) |

HIGH (should fix before publish)

| Rule | Description | |------|-------------| | USE WHEN present | Description should include trigger conditions | | DON'T USE WHEN present | Description should include anti-triggers | | OUTPUTS present | Description should state what the skill produces | | Commands section | Body should have a section listing invocation phrases | | Workflow section | Body should have a step-by-step workflow | | author present | Frontmatter should identify the author | | version is semver | Must match X.Y.Z pattern exactly |

MEDIUM (nice to fix)

| Rule | Description | |------|-------------| | tags present | Helps with discoverability | | price set | Should be explicit (0 or dollar amount) | | Prerequisites section | Helps users know what's needed before install | | Output examples | Workflow section should include example outputs | | Guardrails section | What the skill must not do | | No hardcoded paths | Should not contain /Users/[username]/ or similar personal paths | | No hardcoded accounts | Should not reference specific account handles or org names | | No placeholder text | Remove [YOUR_VALUE] style placeholders before publishing |

LOW (quality suggestions)

| Rule | Description | |------|-------------| | Description length | description field should be 50-500 characters | | Commands variety | At least 3 distinct command phrases | | Heading hierarchy | H2 sections under H1, H3 under H2 — no skipping levels | | Setup section | Should tell user how to install/configure |

Workflow

Receive the Skill

Accept input as:

• A file path: "Validate my skill at skills/my-skill/SKILL.md"
• Pasted content: "Check this SKILL.md: [content]"
• A skill name: "Is the morning-briefing skill correctly formatted?"

Parse and Validate

1. Split on --- delimiters to extract frontmatter and body
2. Parse frontmatter as YAML — catch any parse errors
3. Check all CRITICAL rules first
4. Check HIGH rules
5. Check MEDIUM and LOW rules
6. Compile findings with severity, rule name, and specific fix

Generate Report

Produce the structured conformance report (see Output Format below). Route findings by severity. Include actionable fix recommendations for every HIGH and MEDIUM finding.

Offer to Fix

After the report, offer: "Want me to rewrite this SKILL.md with all issues fixed?"

If yes:

• Preserve all existing content
• Fix structural issues (add missing sections, clean frontmatter)
• Flag content that needs human input (placeholder text, hardcoded values)
• Output corrected SKILL.md ready to copy-paste

Output Format

=== OPENCLAW CONFORMANCE REPORT ===
Skill:   [name or "unknown"]
File:    [path if provided]
Checked: [timestamp]

VERDICT: READY | FIX BEFORE PUBLISH | BLOCKED

--- CRITICAL (0) ---
--- HIGH (2) ---
  Missing USE WHEN in description — agent won't know when to invoke this
  No Commands section — add a "## Commands" block with invocation phrases
--- MEDIUM (1) ---
  Hardcoded path: /Users/raphtesfaye/ — replace with a config variable
--- LOW (0) ---

RECOMMENDATIONS:
1. [Specific, actionable fix for each HIGH finding]
2. [Specific, actionable fix for each MEDIUM finding]

Quick Reference: Minimal Valid SKILL.md

---
name: my-skill-name
description: >
  What this skill does in 1-2 sentences.
  USE WHEN: [trigger phrases and conditions]
  DON'T USE WHEN: [anti-trigger conditions]
  OUTPUTS: [what the skill produces]
version: 1.1.0
author: YourName
---

# My Skill Name

Clear description of what this skill does and why it exists.

## Prerequisites

- Any requirements before this skill works

## Commands

- "Natural phrase that triggers this skill"
- "Another trigger phrase"
- "One more variant"

## Workflow

1. Step one
2. Step two
3. Step three

## Output Format

Description of what gets produced, with an example if helpful.

## Guardrails

- Things this skill must never do

Common Fixes

name field wrong format

# Wrong
name: My Skill Name
name: mySkillName
name: my_skill_name

# Correct
name: my-skill-name

description missing USE WHEN / DON'T USE WHEN

# Weak
description: Validates SKILL.md files.

# Strong
description: >
  Validates SKILL.md files against the OpenClaw standard.
  USE WHEN: User asks to validate, check, or fix a SKILL.md. Keywords: "conform", "validate", "check skill format".
  DON'T USE WHEN: User wants security scanning (use skill-inspector). Not for reviewing content quality.
  OUTPUTS: Conformance report and optionally a corrected SKILL.md.

Hardcoded personal paths

# Wrong — remove before publishing
log_path: "/Users/raphtesfaye/.openclaw/logs/skill.jsonl"

# Correct — use config variable
log_path: "${OPENCLAW_WORKSPACE}/logs/skill.jsonl"

Missing version

# Add this if missing
version: 1.1.0

Guardrails

• Read-only by default. Never modifies files unless explicitly asked to fix.
• Preserve intent. When fixing, keeps all original content; only adjusts structure.
• Flag, don't delete. Hardcoded values get flagged with a comment, not silently removed.
• No security judgments. Conformance is about format, not safety. Defers to skill-inspector for security audits.
• Self-applicable. This skill's own SKILL.md must pass its own conformance check.
• No content quality judgments. Does not evaluate whether a skill's instructions are good — only whether they are correctly structured.

Integration with ClawMart Workflow

Run this before every POST /listings/{id}/versions upload:

1. Write skill — draft your SKILL.md
2. Conformance check — run this skill: "Validate my SKILL.md at [path]"
3. Security scan — run skill-inspector: "Inspect [path] before I publish"
4. Publish — use clawmart-manager to upload the validated package

Why Free?

Every skill published to ClawMart passes through format validation. If that validation lives behind a paywall, authors skip it and the catalog fills with malformed listings that never trigger correctly. This stays free so the entire ecosystem stays well-formed.