skeall

What this skill does

# Skeall

Create, improve, and audit Agent Skills following the [Agent Skills open standard](https://agentskills.io). This skill encodes lessons from real-world skill development and cross-platform compatibility testing.

## Quick start

```text
/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](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:

```text
{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

| Problem | Fix |
|---------|-----|
| Body over 5000 tokens | Move detail sections to references/ |
| Redundant content | Single source of truth, reference elsewhere |
| Persona-based framing | Switch to instruction-based framing |
| Missing trigger phrases | Add keywords to description field |
| Platform-specific patterns | Replace with universal formatting |
| No progressive disclosure | Add routing table to reference files |

---

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

```text
## 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

| Input | Response |
|-------|----------|
| No SKILL.md found at path | "No skill found at {path}. Did you mean `--create`?" |
| Empty directory for `--scan-all` | "No skills found in {dir}. Skills must have a SKILL.md file." |
| Invalid YAML frontmatter | Report the parse error, suggest fixing frontmatter first |
| `--improve` on non-skill file | "Not a valid skill (no YAML frontmatter). Try `--create` instead." |
| `--improve` on a skill scoring 10/10 | "Scan found 0 issues (score 10.0/10). No changes needed. Consider running trigger and functional tests." |

---

## Agent Skills spec reference

### Frontmatter (required)

```yaml
---
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:

```yaml
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

```text
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

| Level | Content | Budget |
|-------|---------|--------|
| Metadata (YAML frontmatter) | name + description | ~100 tokens |
| Instructions (SKILL.md body) | Always loaded by LLM | < 5000 tokens |
| References (each file) | Loaded on demand | ~2000-3000 tokens each |

**Estimat