Safe Skill Evolver

SKILL.md

# Skill Evolver

**A safe, diff-based skill builder and optimizer for OpenClaw.**

**NEVER applies changes automatically. Always suggests diffs and waits for explicit user confirmation.**

---

## When to Use

Use this skill when the user wants to:

1. **Create a new skill** — from scratch or based on an existing template
2. **Improve an existing skill** — analyze errors, feedback, or usage patterns and suggest enhancements
3. **Audit/review a skill** — check quality, security, completeness of any SKILL.md
4. **Migrate or refactor** — restructure skills between workspaces, vaults, or formats

---

## Core Principles

### Safety First
- **NEVER write files without explicit user confirmation.**
- **ALWAYS present a diff/preview before applying changes.**
- **NEVER execute shell commands from skill logic.**
- Skills can read anything; they can only write what the user explicitly approves.

### Transparent Process
Every operation follows this workflow:

```
ANALYZE → SUGGEST → REVIEW → CONFIRM → APPLY
```

- **Analyze:** Read existing files, understand context, identify gaps or issues.
- **Suggest:** Generate proposed changes as a clear diff or structured preview.
- **Review:** Explain *why* each change is recommended (rationale).
- **Confirm:** Wait for explicit user approval ("ja", "ok", "apply", "bestätigen").
- **Apply:** Only then write files, create directories, or modify skills.

---

## Skill Anatomy

A valid OpenClaw skill requires:

| Component | Required | Description |
|-----------|----------|-------------|
| `SKILL.md` | ✅ Yes | Core definition: triggers, workflow, safety rules, examples |
| `scripts/` | ⚪ Optional | Helper scripts (Python, PowerShell, JS) |
| `templates/` | ⚪ Optional | Reusable templates for generating new skills |
| `references/` | ⚪ Optional | External docs, patterns, examples referenced by SKILL.md |
| `README.md` | ⚪ Optional | Human-friendly overview for ClawHub publishing |
| `LICENSE` | ⚪ Optional | License file for distribution |

### SKILL.md Structure

```markdown
# Skill Name

## When to Use
[Clear trigger conditions]

## Core Principles
[Safety rules, boundaries]

## Workflow
[Step-by-step process]

## Tools / Scripts
[Reference to helper scripts]

## Examples
[Concrete usage examples]

## Safety & Boundaries
[What NOT to do]
```

---

## Workflows

### 1. Create New Skill (Builder Mode)

**Trigger:** User says "create skill for X", "build a skill that does Y", "new SKILL.md for Z"

**Steps:**

1. **Gather Requirements**
   - What problem does the skill solve?
   - What triggers should activate it?
   - What tools/commands does it need?
   - What are the safety boundaries?

2. **Select or Design Template**
   - For simple skills: use `templates/basic_skill.md`
   - For tool-heavy skills: use `templates/tool_skill.md`
   - For complex workflows: use `templates/workflow_skill.md`

3. **Generate Draft**
   - Fill template with gathered requirements
   - Ensure all required sections are present
   - Add concrete examples

4. **Present Diff**
   - Show the complete proposed SKILL.md
   - Highlight: triggers, safety rules, boundaries
   - Ask for confirmation

5. **Apply on Confirm**
   - Create directory: `<skill-name>/`
   - Write `SKILL.md`
   - Create subdirectories (`scripts/`, `templates/`) if needed
   - Report success and next steps

---

### 2. Improve Existing Skill (Evolver Mode)

**Trigger:** User says "improve skill X", "optimize this skill", "skill Y has errors", "evolve skill Z"

**Steps:**

1. **Analyze Current State**
   - Read the existing `SKILL.md`
   - Check for: completeness, clarity, safety gaps, outdated info
   - If error reports exist, read `ERRORS.md` or session logs
   - Identify what's working and what's not

2. **Identify Improvement Opportunities**

   | Category | What to Check |
   |----------|---------------|
   | **Triggers** | Are trigger conditions clear and complete? |
   | **Workflow** | Is the step-by-step process logical and safe? |
   | **Safety** | Are boundaries explicit? Is auto-write prevented? |
   | **Examples** | Are there concrete, realistic usage examples? |
   | **Tools** | Are referenced scripts still valid and secure? |
   | **Format** | Follows OpenClaw SKILL.md conventions? |

3. **Generate Diff**
   - Present changes as `before → after` blocks
   - Group by category (triggers, workflow, safety, examples)
   - Explain rationale for each change

4. **Review with User**
   - Summarize: "I suggest 5 changes: 2 safety improvements, 1 new trigger, 2 clarified examples"
   - Show full diff
   - Ask: "Soll ich diese Änderungen übernehmen?"

5. **Apply on Confirm**
   - Update `SKILL.md` (backup old version)
   - Update related scripts/templates if affected
   - Report what changed and why

---

### 3. Audit / Review Mode

**Trigger:** User says "review this skill", "audit skill X", "is this skill safe?"

**Steps:**

1. Read the complete skill directory
2. Check against quality checklist (see below)
3. Output structured report with:
   - ✅ Strengths
   - ⚠️ Gaps / Risks
   - 💡 Improvement suggestions
4. **Do NOT modify anything** — this is read-only

---

## Quality Checklist

When auditing or improving a skill, verify:

### Completeness
- [ ] `SKILL.md` exists and is non-empty
- [ ] "When to Use" section is clear and specific
- [ ] At least one concrete usage example
- [ ] All referenced scripts/templates exist

### Safety
- [ ] Explicit "never auto-execute" rule present
- [ ] External actions (write, exec) require confirmation
- [ ] No hardcoded secrets or credentials
- [ ] Boundary conditions documented (what NOT to do)

### Clarity
- [ ] Trigger conditions are unambiguous
- [ ] Workflow steps are numbered or clearly sequenced
- [ ] Technical terms are explained or linked
- [ ] Examples cover success AND error cases

### Maintainability
- [ ] Version/tag noted
- [ ] Last updated date present
- [ ] Changelog if skill evolved
- [ ] Dependencies documented

---

## Templates

Use the templates in `templates/` directory:

- **`basic_skill.md`** — Simple knowledge/pattern skill (no scripts)
- **`tool_skill.md`** — Skill wrapping scripts or external tools
- **`workflow_skill.md`** — Multi-step process skill with decision trees
- **`evolver_task.md`** — Task template for recording improvement opportunities

---

## Scripts

### `scripts/analyze_skill.py`
Reads a SKILL.md and returns structured analysis:
- Word count, section completeness
- Trigger clarity score
- Safety rule presence
- Example count

### `scripts/generate_diff.py`
Compares two SKILL.md versions and outputs a human-readable diff.

### `scripts/validate_skill.py`
Checks a skill directory against the Quality Checklist above.

---

## Safety & Boundaries

### NEVER
- Write or modify any file without explicit user confirmation
- Confirm before write: Always ask user before writing files
- Confirm before execute: Always ask user before running commands
- Execute shell commands from skill logic without approval
- Auto-publish skills to ClawHub without review
- Delete existing skills without backup
- Ignore safety warnings during audit

### ALWAYS
- Present a clear diff before applying changes
- Explain WHY each change is suggested
- Backup the old version before overwriting
- Respect user rejection — if they say "nein", stop immediately
- Log what was changed in `LEARNINGS.md` or session notes

### WHEN IN DOUBT
- Ask the user before proceeding
- Prefer read-only analysis over automatic modification
- Document uncertainty in the suggestion rationale

---

## Examples

### Example 1: Create New Skill

**User:** *"Ich brauch einen Skill für GPU-Transkription mit faster-whisper"*

**Skill Evolver:**
1. Gathers requirements: Audio file path, model size, language
2. Selects `tool_skill.md` template
3. Generates draft with:
   - Triggers: User mentions "transcribe", "whisper", "audio to text"
   - Workflow: Validate path → Check GPU → Run faster-whisper → Return text
   - Safety: Never auto-delete audio files, validate paths before reading
4. Presents complete SKILL.md
5. **Waits for confirmation:** *"Soll ich diesen Skill als `gpu-transcribe` anlegen?"*
6. On "ja": Creates `gpu-transcribe/SKILL.md` and reports success

### Example 2: Improve Existing Skill

**User:** *"Der paperclip-skill startet manchmal Embedded-Postgres, obwohl externe DB konfiguriert ist"*

**Skill Evolver:**
1. Reads existing paperclip SKILL.md
2. Analyzes: Missing environment variable check in startup workflow
3. Identifies gap: No validation of `DATABASE_URL` before fallback to embedded
4. Generates diff:
   - **Before:** "Start paperclip → if no DB, use embedded"
   - **After:** "Check DATABASE_URL env var → if set, validate connection → only if unset/missing, warn user and abort (never auto-start embedded)"
5. **Presents diff with rationale**
6. On confirmation: Updates SKILL.md, backs up old version

### Example 3: Audit Skill for Safety

**User:** *"Kannst du den evolver-skill von ClawHub auditen?"*

**Skill Evolver:**
1. Reads the skill's files (SKILL.md, scripts, etc.)
2. Checks against Quality Checklist
3. Outputs report:
   - ✅ Good: Clear triggers, structured workflow
   - ⚠️ Risk: Script references external URLs without validation
   - ⚠️ Risk: No explicit "ask before write" boundary
   - 💡 Suggest: Add URL whitelist, add confirmation rule
4. **Does NOT modify anything** — read-only audit

---

## Metadata

- **Version:** 1.0.0
- **Created:** 2026-05-28
- **Updated:** 2026-05-28
- **Author:** OpenClaw (for Andreas)
- **License:** MIT-0
- **Tags:** skill-builder, skill-optimizer, diff-based, safe, workflow