Eigenskill Builder

The meta-skill. This skill teaches AI agents how to build, validate, and publish skills on ClawHub. If you're creating a new skill, this is your blueprint.

When to Use

• - Creating a new skill from scratch
• Validating an existing skill against quality standards
• Publishing a skill to ClawHub
• Designing skill descriptions with proper trigger/exclusion boundaries
• Setting up references/ directories for supplementary material
• Planning skill graphs for large skill libraries (50+)

When NOT to Use

• - Writing prompts or prompt templates (use a prompt-engineering skill)
• Building agent memory systems (use agent-memory-architecture)
• Orchestrating multiple agents (use agent-orchestration)
• Fine-tuning models or training data preparation
• Building MCP servers or tools (that's tool development, not skill development)

---

1. Skill Anatomy

Every skill is a directory containing at minimum a SKILL.md file. The directory name should be kebab-case and match the skill name.

Directory Structure

CODEBLOCK0

SKILL.md Structure

CODEBLOCK1

---

2. YAML Frontmatter Specification

The frontmatter block is the machine-readable identity of the skill. It must be valid YAML between --- delimiters.

Required Fields

Field	Type	Description	Example
INLINECODE2	string	Kebab-case identifier, unique on ClawHub	INLINECODE3
INLINECODE4

string | Single-quoted paragraph. Must include trigger AND exclusion. | See below | | license | string | SPDX identifier | MIT, Apache-2.0, CC-BY-4.0 |

Optional Fields

Field	Type	Description	Example
INLINECODE9	string	Semver	INLINECODE10
INLINECODE11

string | Creator name or handle | @openclaw | | tags | list | Discovery tags | [finance, analysis, cfp] | | depends | list | Other skills this depends on | [agent-memory-architecture] | | metadata.openclaw.emoji | string | Display emoji on ClawHub | '💰' | | metadata.openclaw.tier | string | Complexity tier | foundational, intermediate, advanced | | metadata.openclaw.models | list | Models this skill works best with | [claude-opus-4-6, claude-sonnet-4-6] |

Description Best Practices

The description field is the most important field. It's what agents use to decide whether to load the skill. It must be:

1. 1. Specific — list the concrete things the skill covers
2. Bounded — say what it does NOT cover
3. Trigger-rich — include keywords an agent would search for

Good:
CODEBLOCK2

Bad:
CODEBLOCK3

Bad:

description: 'Comprehensive enterprise-grade financial analysis solution leveraging AI-powered insights for transformative business intelligence.'

---

3. References Directory Convention

The references/ directory holds supplementary material that the skill can point to but that shouldn't be in the main SKILL.md (to keep it focused).

Rules

1. 1. One level deep only — references/file.md is fine. references/sub/file.md is not.
2. Never chain references — a reference file should not reference another reference file. References are leaves, not nodes.
3. Keep references self-contained — each file should make sense on its own without reading SKILL.md first.
4. Name descriptively — api-authentication.md not ref1.md.

When to Use References vs Inline Content

Content Type	Location	Rationale
Core methodology	SKILL.md	Agent needs this to execute
Quick reference tables

SKILL.md | Frequently accessed | | Detailed API docs | references/ | Only needed for specific tasks | | Extended examples | references/ | Useful but not essential | | Cheat sheets | references/ | Quick lookup, not learning | | Historical context | references/ | Background, not action |

Example References Directory

CODEBLOCK5

---

4. Negative Boundaries

Every skill MUST define what it does NOT do. This is not optional — it's the most important part of skill design after the core content.

Why Negative Boundaries Matter

Without negative boundaries:

• - Agents load wrong skills for tasks → bad output
• Skills overlap silently → conflicts and confusion
• Users don't know where one skill ends and another begins

The Exclusion Checklist

For every skill, explicitly answer:

1. 1. Adjacent skills — What similar skills exist that this one is NOT?
2. Common misconceptions — What do people assume this covers that it doesn't?
3. Scope ceiling — What's the most complex thing this skill can handle? What's above that ceiling?
4. Scope floor — What's too simple for this skill? (e.g., "don't use this to add two numbers")

Template

CODEBLOCK6

Example

CODEBLOCK7

---

5. Description Interview Process

When building a new skill, interview yourself (or the skill author) with these questions to produce a high-quality description.

The Interview

Step 1: Define Triggers

CODEBLOCK8

Step 2: Define Exclusions

CODEBLOCK9

Step 3: Define Dependencies

CODEBLOCK10

Step 4: Write the Description

Combine triggers, exclusions, and dependencies into a single paragraph:

CODEBLOCK11

Step 5: Test the Description

Ask: "If an agent read only this description, would it correctly decide to load or skip this skill for these 10 test queries?"

Test with 5 queries that SHOULD trigger and 5 that should NOT.

---

6. Scripts Directory

The scripts/ directory holds automation for skill lifecycle operations.

Common Scripts

CODEBLOCK12

CODEBLOCK13

---

7. ClawHub CLI Workflow

ClawHub is the registry for discovering, installing, and publishing skills.

Commands

CODEBLOCK14

Publishing Checklist (Pre-publish)

Before running clawhub publish:

1. 1. scripts/validate.sh passes
2. Description includes trigger AND exclusion language
3. All examples are tested and working
4. References are one level deep only
5. No secrets, API keys, or credentials in any file
6. License is specified and compatible
7. Version is bumped if updating existing skill

Publishing Flow

CODEBLOCK15

---

8. Quality Checklist

Score every skill against these 10 criteria before publishing.

#	Criterion	Pass/Fail	Notes
1	SKILL.md exists with valid YAML frontmatter	Required	Must parse without errors
2

Name is kebab-case and unique | Required | Check clawhub search first |
| 3 | Description is specific with triggers AND exclusions | Required | >50 chars, <500 chars |
| 4 | "When to Use" section with 3+ bullet points | Required | Concrete, not vague |
| 5 | "When NOT to Use" section with 3+ bullet points | Required | Names alternative skills |
| 6 | Actionable content — agent can execute, not just read | Required | Include templates, formulas, steps |
| 7 | Examples for every major concept | Recommended | Show input → output |
| 8 | References one level deep (if references/ exists) | Required | No nested references |
| 9 | No secrets or credentials in any file | Required | Scan before publish |
| 10 | License specified and SPDX-valid | Required | MIT, Apache-2.0, etc. |

Scoring

CODEBLOCK16

---

9. Version Management

Semver for Skills

CODEBLOCK17

Version Bump Rules

Change	Bump	Example
Fix a typo in an example	PATCH	1.0.0 → 1.0.1
Add a new section on ratio analysis

MINOR | 1.0.1 → 1.1.0 | | Restructure from 5 sections to 10 | MAJOR | 1.1.0 → 2.0.0 | | Change the description triggers | MAJOR | 2.0.0 → 3.0.0 | | Add a reference file | MINOR | 1.0.0 → 1.1.0 | | Update examples for new API version | MINOR | 1.1.0 → 1.2.0 |

Changelog Convention

Add a ## Changelog section at the bottom of SKILL.md for significant versions:

CODEBLOCK18

---

10. Skill Graphs

When your skill library grows past ~50 skills, you need a way to discover relationships between skills. Skill graphs solve this.

Concept

Each skill can declare relationships to other skills using two mechanisms:

1. 1. YAML depends field — hard dependencies (skill won't work without these)
2. Wikilinks in content — soft references (related but not required)

YAML Dependencies

CODEBLOCK19

Wikilinks in Content

Use [[skill-name]] syntax to create soft links:

CODEBLOCK20

Graph Queries

With a skill graph, you can answer:

CODEBLOCK21

Building the Graph

CODEBLOCK22

Visualization

For small libraries (<20), a simple ASCII graph works:

CODEBLOCK23

For larger libraries, export to DOT format and render with Graphviz, or use a JSON graph viewer.