EigenSkill Builder

Meta-skill for building and publishing agent skills on ClawHub. Covers skill structure, YAML frontmatter specification, references directory convention, nega...

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

skills/
  my-skill-name/
    SKILL.md              # Required: the skill definition
    references/           # Optional: supplementary material
      api-docs.md
      examples.md
      cheatsheet.md
    scripts/              # Optional: automation scripts
      validate.sh
      install.sh

SKILL.md Structure

---
name: my-skill-name
description: 'One paragraph. What it does. When to trigger. When NOT to trigger.'
license: MIT
metadata:
  openclaw:
    emoji: '🔧'
---

# Skill Title

[Brief overview — 2-3 sentences max]

## When to Use
[Bulleted list of trigger conditions]

## When NOT to Use
[Bulleted list of exclusion conditions — REQUIRED]

---

## Section 1: [Topic]
[Content with examples]

## Section 2: [Topic]
[Content with examples]

...

---

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
name	string	Kebab-case identifier, unique on ClawHub	financial-analysis-agent
description	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
version	string	Semver	1.0.0
author	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. 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:

description: 'Financial analysis skill for AI agents. Covers variance analysis, cash flow forecasting, month-end close automation, CFO commentary generation. Do NOT use for tax preparation, audit opinions, or regulatory filings.'

Bad:

description: 'A skill for finance stuff.'

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. 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

skills/financial-analysis-agent/
  SKILL.md
  references/
    gaap-ifrs-differences.md      # Detailed comparison table
    ratio-benchmarks-by-industry.md  # Industry-specific ratio ranges
    asc-606-checklist.md           # Revenue recognition deep dive
    sample-board-package.md        # Example board reporting package

---

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. 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

## When NOT to Use

- [Adjacent skill 1] — use [other-skill-name] instead
- [Adjacent skill 2] — use [other-skill-name] instead
- [Common misconception] — this skill does not cover [X]
- Tasks requiring [thing above scope ceiling] — escalate to [human/specialist]
- Simple [thing below scope floor] — just do it directly, no skill needed

Example

## When NOT to Use

- Tax preparation or tax advisory — use crypto-tax-agent or consult a CPA
- Audit opinions or attestation — requires human CPA, not an agent skill
- Regulatory filings (SEC 10-K, etc.) — use a compliance-specific skill
- Simple arithmetic or unit conversions — just calculate directly
- Investment advice or stock picks — this is analysis, not advisory

---

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

Q: What specific phrases would someone say that should activate this skill?
A: List 5-10 trigger phrases.

Example:
- "Analyze the variance between budget and actual"
- "Generate a 13-week cash flow forecast"
- "Write CFO commentary for the board package"
- "Review the financial statements before close"

Step 2: Define Exclusions

Q: What phrases sound similar but should NOT activate this skill?
A: List 5-10 exclusion phrases.

Example:
- "File our tax return" → tax skill, not this one
- "Should we invest in X stock?" → not advisory
- "Audit the financial statements" → requires CPA

Step 3: Define Dependencies

Q: What other skills or knowledge does this skill assume?
A: List prerequisites.

Example:
- Basic accounting knowledge (debits/credits)
- Access to financial data (GL, subledger)
- Familiarity with Excel/Sheets for output formatting

Step 4: Write the Description

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

description: '[What it does — 1 sentence]. Covers [trigger keywords]. Assumes [dependencies]. Do NOT use for [exclusions].'

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

# scripts/validate.sh — Check skill quality
#!/bin/bash
set -euo pipefail

SKILL_DIR="$(dirname "$0")/.."
SKILL_FILE="$SKILL_DIR/SKILL.md"

# Check SKILL.md exists
[[ -f "$SKILL_FILE" ]] || { echo "FAIL: SKILL.md not found"; exit 1; }

# Check frontmatter exists
head -1 "$SKILL_FILE" | grep -q "^---$" || { echo "FAIL: Missing frontmatter"; exit 1; }

# Check required fields
grep -q "^name:" "$SKILL_FILE" || { echo "FAIL: Missing name field"; exit 1; }
grep -q "^description:" "$SKILL_FILE" || { echo "FAIL: Missing description field"; exit 1; }
grep -q "^license:" "$SKILL_FILE" || { echo "FAIL: Missing license field"; exit 1; }

# Check negative boundaries exist
grep -q "When NOT to Use" "$SKILL_FILE" || { echo "FAIL: Missing negative boundaries"; exit 1; }

# Check description includes exclusions
DESC=$(grep "^description:" "$SKILL_FILE")
echo "$DESC" | grep -qi "not\|don't\|do not\|except\|exclud" || {
    echo "WARN: Description may lack exclusion language"
}

# Check references depth
if [[ -d "$SKILL_DIR/references" ]]; then
    DEPTH=$(find "$SKILL_DIR/references" -mindepth 2 -type f | wc -l)
    [[ "$DEPTH" -eq 0 ]] || { echo "FAIL: References nested >1 level deep"; exit 1; }
fi

echo "PASS: Skill validation complete"

# scripts/install.sh — Install skill into agent workspace
#!/bin/bash
set -euo pipefail

SKILL_NAME="$(basename "$(dirname "$0")/..")"
TARGET="${1:-$HOME/.openclaw/workspace/skills}"

echo "Installing $SKILL_NAME to $TARGET/$SKILL_NAME"
cp -r "$(dirname "$0")/.." "$TARGET/$SKILL_NAME"
echo "Done. Skill available at $TARGET/$SKILL_NAME/SKILL.md"

---

7. ClawHub CLI Workflow

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

Commands

# Search for skills
clawhub search "financial analysis"
clawhub search --tag finance
clawhub search --emoji 💰

# View skill details
clawhub info financial-analysis-agent
clawhub info financial-analysis-agent --versions

# Install a skill
clawhub install financial-analysis-agent
clawhub install financial-analysis-agent@1.2.0
clawhub install financial-analysis-agent --path ./my-skills/

# Publish a skill
clawhub publish ./skills/my-skill/
clawhub publish ./skills/my-skill/ --dry-run  # Validate without publishing

# Update skills
clawhub update                          # Update all installed skills
clawhub update financial-analysis-agent  # Update specific skill
clawhub outdated                         # List skills with available updates

# List installed skills
clawhub list
clawhub list --format json

Publishing Checklist (Pre-publish)

Before running clawhub publish:

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

1. Author creates skill locally
2. Run: clawhub publish ./skills/my-skill/ --dry-run
3. Fix any validation errors
4. Run: clawhub publish ./skills/my-skill/
5. ClawHub assigns a unique ID and indexes the skill
6. Skill appears in search results within 5 minutes
7. Other agents can install via: clawhub install my-skill

---

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

10/10 — Ready to publish
8-9/10 — Minor fixes needed, publishable
6-7/10 — Needs work, don't publish yet
<6/10 — Fundamental issues, redesign needed

---

9. Version Management

Semver for Skills

MAJOR.MINOR.PATCH

MAJOR — Breaking changes to skill structure or content that would change agent behavior
MINOR — New content sections, expanded examples, new references
PATCH — Typo fixes, clarifications, formatting improvements

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:

## Changelog

### 2.0.0 (2026-03-15)
- Restructured from 5 to 9 sections
- Added aging analysis and bank reconciliation
- Breaking: removed deprecated ratio shortcuts

### 1.1.0 (2026-03-01)
- Added CFO commentary templates
- New reference: sample-board-package.md

### 1.0.0 (2026-02-15)
- Initial release

---

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. YAML depends field — hard dependencies (skill won't work without these)
2. Wikilinks in content — soft references (related but not required)

YAML Dependencies

depends:
  - agent-memory-architecture    # Required: this skill uses memory patterns
  - agent-orchestration          # Required: this skill uses orchestration patterns

Wikilinks in Content

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

For memory patterns used in financial analysis workflows, see [[agent-memory-architecture]].

When orchestrating multiple financial analysis agents, apply the patterns in [[agent-orchestration]].

Graph Queries

With a skill graph, you can answer:

"What skills does financial-analysis-agent depend on?"
  → agent-memory-architecture, agent-orchestration

"What skills reference financial-analysis-agent?"
  → eigenskill-builder (as example), cfo-reporting-agent

"What's the shortest path from crypto-tax-agent to agent-orchestration?"
  → crypto-tax-agent → financial-analysis-agent → agent-orchestration

"What are the foundational skills (most depended on)?"
  → agent-memory-architecture (12 dependents)
  → agent-orchestration (8 dependents)
  → eigenskill-builder (6 dependents)

Building the Graph

import yaml
import re
from pathlib import Path

def build_skill_graph(skills_dir: Path) -> dict:
    """Build a dependency graph from all skills."""
    graph = {"nodes": {}, "edges": []}

    for skill_dir in skills_dir.iterdir():
        skill_file = skill_dir / "SKILL.md"
        if not skill_file.exists():
            continue

        content = skill_file.read_text()

        # Parse frontmatter
        fm_match = re.search(r'^---\n(.*?)\n---', content, re.DOTALL)
        if not fm_match:
            continue
        fm = yaml.safe_load(fm_match.group(1))

        name = fm.get("name", skill_dir.name)
        graph["nodes"][name] = {
            "description": fm.get("description", ""),
            "emoji": fm.get("metadata", {}).get("openclaw", {}).get("emoji", ""),
        }

        # Hard dependencies (YAML)
        for dep in fm.get("depends", []):
            graph["edges"].append({
                "from": name, "to": dep, "type": "depends"
            })

        # Soft references (wikilinks)
        for link in re.findall(r'\[\[([\w-]+)\]\]', content):
            if link != name:  # No self-links
                graph["edges"].append({
                    "from": name, "to": link, "type": "references"
                })

    return graph

Visualization

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

eigenskill-builder ──depends──▶ agent-orchestration
       │                              ▲
       │                              │
       ▼                              │
financial-analysis-agent ──references─┘
       │
       ▼
crypto-tax-agent

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