Skill: samledger67-dotcom/eigenskill-builder (version 98.0.1)

--- name: eigenskill-builder description: 'Meta-skill for building and publishing agent skills on ClawHub. Covers skill structure, YAML frontmatter specification, references directory convention, negative boundaries, installation instructions, ClawHub CLI workflow, and quality checklist. The skill that teaches agents to build skills. Do NOT use for prompt engineering, agent memory, or orchestration — those have their own dedicated skills.' license: MIT metadata: openclaw: emoji: '🔄' --- # 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 ``` 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 ```markdown --- 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:** ```yaml 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:** ```yaml description: 'A skill for finance stuff.' ``` **Bad:** ```yaml 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 ```markdown ## 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 ```markdown ## 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: ```yaml 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 ```bash # 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" ``` ```bash # 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 ```bash # 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: ```markdown ## 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 ```yaml 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: ```markdown 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 ```python 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.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)