skill-perfection

Files (2)

• SKILL.md
• preflight.py · scripts/

SKILL.md (first lines)

# Skill Perfection

A systematic process for auditing and fixing plugin skills in a single pass.

## Core Principle

**Audit + Fix in One Pass**: When you find an issue, fix it immediately, then continue. This eliminates redundant research and multiple iterations.

## Process Overview

```
[Optional Preflight] → Audit+Fix (single pass) → Verify (spot-check) → Report
```

## Phase 1: Preflight (Optional, Advisory)

A Python-based preflight script is bundled for **Python-heavy skills only**. 

### When to Use Preflight

| Skill Content | Use Preflight? |
|---------------|----------------|
| Mostly Python code blocks | ✅ Yes |
| Mixed Python + other languages | ⚠️ Optional (Python blocks only) |
| Non-Python (JS, Rust, Go, etc.) | ❌ Skip, go to Phase 2 |
| Skill about the preflight script itself | ❌ Skip (conflict of interest) |

### Running Preflight

```bash
uv run python ${SKILL_DIR}/scripts/preflight.py <path-to-skill.md> --no-urls
```

### Interpreting Results

| Result | Action |
|--------|--------|
| `✅ PASSED` | Good signal. Proceed to Phase 2, trust syntax is valid. |
| `❌ FAILED` with clear errors (syntax error at line X) | Fix those specific issues, then proceed to Phase 2. |
| `❌ FAILED` with confusing/many errors | **Ignore preflight entirely.** Proceed to Phase 2, let LLM verify. |
| Script crashes or hangs | **Ignore preflight entirely.** Proceed to Phase 2. |

### Key Rule: Preflight is Advisory

**The preflight script is a helper, not a gatekeeper.** If it produces confusing output, skip it. The LLM-based Phase 2 is always authoritative.

Signs to ignore preflight:
- More than 10 errors on a skill that "looks fine"
- Errors that don't make sense (line numbers don't match)
- Python tracebacks from the script itself
- Timeouts or hanging

**When in doubt, skip preflight and let the LLM verify everything.**

## Phase 2: Audit + Fix (Single Pass) - THE CORE

This is the main phase. Work through the skill file section by section.

### 2.1 Identify the Technology

From the skill's content, identify:
- Primary technology/framework (e.g., LangGraph, React, Axum, Go-kit)
- Version constraints if mentioned
- Official documentation domain

### 2.2 Research Strategy

**Batch similar lookups** to minimize web calls:

```
Example: For a skill with 10 import statements from the same package,
do ONE search that covers them all, not 10 separate searches.
```

**Documentation priority**:
1. Official docs (use `site:` filter)
2. Official GitHub repo (examples, tests, README)
3. Package registry (PyPI, npm, crates.io, pkg.go.dev)
4. Official blog/changelog

### 2.3 For Each Verifiable Item

| Item Type | What to Verify |
|-----------|---------------|
| Import/require statement | Package exists, path is current, not deprecated |
| API call | Signature matches official docs, parameters correct |
| Code example | Would execute, complete imports, correct syntax |
| URL/link | Accessible (WebFetch), points to claimed content |
| Version claim | Current/accurate |
| Best practice claim | Aligned with official recommendations |

### 2.4 Fix-As-You-Go

When you find an issue:

1. **STOP** auditing that section
2. **FIX** the issue immediately (Edit tool)
3. **LOG** the change in memory: `{location, old, new, reason, source_url}`
4. **CONTINUE** auditing

**All severities get fixed in one pass** - don't defer anything.

### 2.5 Syntax Verification (LLM-based)

For code blocks, verify syntax by reading carefully:

**Python**: Check for matching parentheses, correct indentation, valid syntax
**JavaScript/TypeScript**: Check for matching braces, valid syntax, correct imports  
**Rust**: Check for matching braces, semicolons, valid syntax
**Go**: Check for matching braces, correct package structure
**Any language**: Apply your knowledge of that language's syntax rules

If unsure about syntax validity, note it but don't block on it - focus on semantic correctness against official docs.

## Phase 3: Verification (Spot-Check)

After completing Phase 2:

1. **Re-read the modified skill file**

From OmidZamani/dspy-skills, MIT.

More from OmidZamani/dspy-skills