Skeall

Skeall

Create, improve, and audit Agent Skills following the Agent Skills open standard. This skill encodes lessons from real-world skill development and cross-platform compatibility testing.

Quick start

/skeall --create              # Interview, then scaffold new skill
/skeall --improve <path>      # Analyze and improve existing skill
/skeall --scan <path>         # Audit only, no changes (report)
/skeall --scan .              # Audit skill in current directory
/skeall --scan-all            # Batch scan all skills in ~/.claude/skills/
/skeall --scan-all <dir>      # Batch scan all skills in custom directory
/skeall --healthcheck <path>  # Runtime check single skill (orphans, deps, env, URLs)
/skeall --healthcheck-all     # Runtime check all skills in ~/.openclaw/skills/
/skeall --healthcheck-all <dir> # Runtime check all skills in custom directory

Mode 1: Create (scaffold a new skill)

Process

1. Interview the user (ask questions 1-4 always, then 5-6 if user hasn't already specified complexity or distribution scope):

   • What does this skill do? (one sentence)
   • What category? Reference / Task / MCP Enhancement / Hybrid. See references/advanced-patterns.md
   • What triggers should activate it? (keywords users would type)
   • Does it accept arguments? (e.g., file path, topic — use $ARGUMENTS or $ARGUMENTS[N] in body)
   • How complex is it? (single file vs references/ needed)
   • Will this skill be shared? (personal / project / public) — affects README, license, metadata

2. Generate the skill structure:

{skill-name}/
├── SKILL.md                    # Core instructions (always loaded)
├── references/                 # On-demand detail files
│   ├── {topic-1}.md
│   └── {topic-2}.md
└── README.md                   # GitHub-facing (optional)

3. Write SKILL.md following these rules:

   • YAML frontmatter with name and description (see Frontmatter section)
   • Body under 500 lines, under 5000 tokens
   • Instruction-based framing, not persona-based
   • Progressive disclosure: core in SKILL.md, details in references/

4. Show the generated SKILL.md to user for review.

5. Run --scan on the generated skill. If any HIGH issues found, fix them before delivering.

Next step: "Optimize with reprompter?" (optional, see Reprompter section). Then suggest installing the skill.

Mode 2: Improve (refactor existing skill)

Process

1. Read SKILL.md first. Read reference files only if scan identifies issues requiring them (broken links, routing table mismatches).
2. Run the scan checklist (see Mode 3).
3. For each issue found, propose a specific before/after edit.
4. Group edits by priority: HIGH first, then MEDIUM, then LOW.
5. Ask user: "Fix all? Review one by one? Or just the HIGHs?" (recommended: fix all HIGHs automatically, review MEDIUMs)
6. Apply approved edits.
7. Re-scan once. If new issues appear, report them but do not enter an infinite fix loop.

Next step: "Run --scan to verify?" or "Commit changes?"

Common improvements

Mode 3: Scan (audit and report)

Process

1. Read the skill's SKILL.md and directory structure.
2. Check every item in the checklist below.
3. Output a severity-tagged report.

Report format

## Skill Audit: {skill-name}

Score: X.X/10

STRUCTURE
  [PASS] S1 -- SKILL.md exists at root
  [FAIL] S3 HIGH -- name does not match directory name
  [WARN] S5 MEDIUM -- No references/ directory

FRONTMATTER
  [PASS] F2 -- Trigger phrases present
  [FAIL] F1 HIGH -- description over 1024 characters

CONTENT
  [WARN] C5 MEDIUM -- Persona-based framing ("You are an expert")
  [FAIL] C3 HIGH -- Same content repeated 3 times (lines 45, 120, 280)

LLM-FRIENDLINESS
  [WARN] L4 MEDIUM -- Unicode arrows instead of markdown tables
  [PASS] L3 -- No emoji markers in headings

SECURITY
  [PASS] SEC1 -- No XML angle brackets in frontmatter
  [PASS] SEC3 -- No hardcoded secrets

CROSS-PLATFORM
  [PASS] X1 -- No {baseDir} placeholders
  [WARN] X4 LOW -- No multi-platform install instructions in README

Total: 3 HIGH | 4 MEDIUM | 1 LOW

Next step after scan: "Want me to fix these? Run /skeall --improve <path>"

Error handling

Agent Skills spec reference

Frontmatter (required)

---
name: my-skill-name
description: What this skill does and when to use it. Include trigger phrases.
---

name rules:

• Must match the parent directory name
• Lowercase alphanumeric with hyphens only (unicode lowercase allowed)
• 1-64 characters, no leading/trailing/consecutive hyphens
• No spaces, no special characters, no reserved words ("anthropic", "claude")
• Recommended: gerund form (processing-pdfs, testing-code) or descriptive noun (pdf-processor)

description rules:

• Explain WHAT it does AND WHEN to use it
• Write in third person ("Processes files", not "I can process" or "You can use")
• Include trigger phrases users would actually type
• Put the most important keyword first (platforms weight first words)
• Spec limit: 1024 characters. Recommended: under 300 for best matching
• Use noun-phrase style ("Guide for X"), not persona style ("Expert in X")
• No XML angle brackets (<, >) in any frontmatter value (injection risk)

Optional frontmatter fields

These are silently ignored by platforms that do not support them:

license: MIT                          # For distributed skills
compatibility: "Node.js 18+"         # Environment requirements (max 500 chars)
metadata:                             # Arbitrary key-value (author, version)
  author: your-name
  version: 1.0.0
allowed-tools: "Bash Read"           # Experimental: space-delimited tool list
user-invocable: true                  # Show in /slash menu (false = hidden but still callable)
disable-model-invocation: true        # Block Claude from auto-loading this skill
argument-hint: "<file-path>"          # Hint shown in /skill autocomplete
model: opus                           # Override model for this skill
context: fork                         # Run in isolated subagent
agent: general-purpose                # Subagent type: general-purpose, Explore, Plan, or custom
hooks:                                # Skill-scoped lifecycle hooks
  PostToolCall: "validate.sh"

Directory structure

skill-name/
├── SKILL.md           # REQUIRED -- core instructions
├── references/        # OPTIONAL -- on-demand detail files
├── scripts/           # OPTIONAL -- executable scripts
├── assets/            # OPTIONAL -- static assets (images, etc.)
└── README.md          # OPTIONAL -- GitHub-facing docs

Token budget

Estimation: ~1.5 tokens per word for mixed code+prose markdown.

Progressive disclosure: SKILL.md body should handle ~70% of user requests. Reference files handle the remaining 30% (detailed workflows, complete examples, edge cases).

Line limits

Scan checklist

Structure checks

Frontmatter checks

Content checks

LLM-friendliness checks

Security checks

Cross-platform checks

Runtime checks (healthcheck mode only)

LLM-friendliness patterns

These patterns come from real cross-platform testing. Apply them when creating or improving skills.

Do

• Tables over prose for structured data (parameters, options, comparisons)
• Single source of truth for any concept explained more than once
• Instruction-based framing: "This skill provides instructions for X. Follow these patterns exactly."
• Imperative verbs: "Call X after Y", "Use Z for W"
• Compact routing table at the top pointing to reference files
• Parameter comments inline in code blocks: providerAddress, // 1st: wallet address
• Copyable progress checklists for multi-step workflows (LLM tracks completion)
• Validation feedback loops for quality-sensitive output (generate, score, retry if needed)
• Consistent freedom level per section — do not mix exact scripts with vague guidance. See references/advanced-patterns.md

Do not

• Persona-based framing: "You are an expert in..." (Claude-leaning, other LLMs respond better to instructions)
• Emoji markers in headings or structural elements (token-expensive, parsed inconsistently). Emoji in frontmatter metadata values is data and acceptable
• Unicode arrows (→, ←) for data flow — use tables or plain prose
• Blockquote warnings at top of SKILL.md (wastes prime token space, primes distrust)
• "When Users Ask" checklists with 10+ items (bury critical rules, use tables instead)
• Synonym cycling for the same concept (confuses LLMs about whether it's the same thing)
• Repeated content (wastes tokens, risks contradictions if copies drift)
• Assuming exclusive activation (other skills may load simultaneously — declare dependencies explicitly)

Description field optimization

Good description pattern:

{Product/Tool name} guide for {primary use case}. Covers {feature list}.
Use this skill for {trigger phrases separated by commas}.

Example:

description: 0G Compute Network guide for decentralized AI inference and fine-tuning.
  Covers chatbots, image generation, speech-to-text, SDK integration, CLI commands.
  Use this skill for any 0G compute, 0G AI, or decentralized GPU question.

Cross-platform compatibility

Universal format (works everywhere)

Only name and description in frontmatter. Standard markdown body. Relative paths. No platform-specific syntax.

Platform discovery paths

Codex-specific extensions

OpenAI Codex adds an optional openai.yaml file alongside SKILL.md for platform metadata (interface, policy, dependencies). SKILL.md itself stays cross-platform. See references/advanced-patterns.md for details.

Things that break cross-platform

Token estimation

Estimate: wc -w SKILL.md × 1.5 (prose) or × 1.7 (code-heavy files).

Budget allocation guide

Severity reference

Mode 4: Batch scan (scan-all)

Scan every skill in a directory at once. Useful for auditing your entire skill collection.

Process

1. List all subdirectories containing SKILL.md in the target path (default: ~/.claude/skills/).
2. Run Mode 3 (scan) on each skill. Output each skill's score as you complete it.
3. Output a summary table sorted by score ascending (worst first).

Report format

## Batch Skill Audit

| Skill | Score | HIGH | MEDIUM | LOW | Status |
|-------|-------|------|--------|-----|--------|
| seo-optimizer | 5/10 | 3 | 2 | 1 | NEEDS WORK |
| reprompter | 6/10 | 2 | 3 | 0 | NEEDS WORK |
| blogger | 7/10 | 1 | 1 | 2 | NEEDS WORK |
| humanizer-enhanced | 8/10 | 0 | 2 | 1 | PASS |

Total: 4 skills scanned
PASS: 1 | NEEDS WORK: 3

Top issues across all skills:
1. [HIGH] C2 reprompter: Body exceeds 5000 tokens (est. 8,200)
2. [HIGH] C3 seo-optimizer: Content repeated 4 times
3. [HIGH] C5 reprompter: Persona-based framing

PASS threshold: Score 7+ with zero HIGH issues.

Next step: "Start with the lowest-scoring skill. Run /skeall --improve <path> on it."

Mode 5: Health check (runtime audit)

Checks whether a skill actually works at runtime — beyond what static scan can catch. Run static scan (Mode 3) first and fix HIGH issues before health check.

Process

1. Run R1-R7 checks against the target skill.
2. For --healthcheck-all: cross-check all skills for duplicates (R2) and trigger collisions (R3).
3. Output severity-tagged report with sections: RUNTIME, DUPLICATES, TRIGGER COLLISIONS.
4. Labels: [FAIL] for HIGH issues (must fix), [WARN] for MEDIUM (runtime risk), [INFO] for LOW.

For detection algorithms, report format examples, and batch output format, see references/healthcheck.md.

Scoring methodology

Formula: Score = max(0, 10 - (HIGHs x 1.5) - min(MEDIUMs x 0.5, 3) - min(LOWs x 0.2, 1))

PASS threshold: Score 7+ AND zero HIGH issues. For detailed examples, see references/scoring.md.

Troubleshooting

References

For detailed checklists and examples, see:

• Anti-patterns with before/after examples
• Runtime health check algorithms and real examples
• Complete SKILL.md template
• Scoring methodology details
• Testing patterns and examples
• Advanced patterns: categories, freedom levels, distribution, MCP, workflows

Testing your skill: After create or improve, test trigger activation (3-5 keyword variants), functional output, and negative (unrelated queries stay quiet). See references/testing.md.

MCP integration: Use fully qualified tool names (mcp__server__tool_name). Document required MCP servers and provide fallbacks. See references/advanced-patterns.md.

Reprompter integration (optional): After --create interview, say "reprompter optimize" to score description variants and validate code examples. Works standalone if reprompter is not installed.