An opinionated tool designed to audit, polish, and optimize existing AI agent SKILL.md files against the agentskills.io standard.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install skill-optimize
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install skill-optimize using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Skill Optimizer?
The Skill Optimizer is a highly specialized developer advocate utility built to polish and refine existing AI agent skills. While creating new skills from scratch requires interactive interviewing, maintaining and improving them requires targeted, structured feedback. This skill runs comprehensive audits directly against the industry-accepted agentskills.io standard, ensuring your agents trigger accurately and perform consistently when integrated into modern frameworks such as Openclaw Skills.
By focusing on concrete, mechanical specifications, agent best practices, and description engineering, this optimizer helps developers iron out bugs, streamline instructions, and cut down token waste. It acts as a fast, reliable assistant to elevate the efficiency of your AI assets.
Skill Optimizer Use Cases
- Reviewing and debugging failing frontmatter specifications in SKILL.md files.
- Improving agent trigger accuracy when an agent is not firing on target prompts.
- Refining long, bloated skill files down to a highly efficient token budget.
- Rewriting vague frontmatter descriptions into clear, imperative intent signals.
- Validating skill compliance prior to publishing them to the Openclaw Skills directory.
How Skill Optimizer Works
- Capture Intent: Identify whether the user needs to fix a triggering issue, resolve spec errors, or restructure content.
- Locate & Snapshot: Scan the workspace to find the targeted SKILL.md file and create a backup original-SKILL.md copy to ensure safe diffing.
- Run 3-Dimension Audit: Evaluate the file across Specification Compliance, Best Practices Alignment, and Description Optimization using built-in checklists and scripts.
- Generate Report: Produce a structured Markdown audit report classifying findings by severity (Blocker, Major, Minor, Nit).
- Apply Interactive Diffs: Present recommended before/after diffs to the user, explaining the underlying rationale, and apply them on approval.
- Validate Changes: Run programmatic tests to confirm the refined skill file remains fully spec-compliant.
Skill Optimizer Setup
Ensure the skill and its bundled resources are cloned or copied to your agent's skill environment. The framework utilizes a Python helper for programmatic validation.
# Navigate to your skill directory
cd path/to/skill-optimizer
# Run the Python audit script against an existing SKILL.md file
python scripts/audit_skill.py /path/to/target/SKILL.md
Ensure that standard YAML and linting dependencies are installed in your Python environment. You can then configure this tool seamlessly within your Openclaw Skills library.
Skill Optimizer Data Schema & Taxonomy
The skill relies on a structured workspace schema to run diagnostics and generate reports:
Directory and Resource Schema
| Path | Purpose |
|---|---|
references/specification-checklist.md |
Contains strict rules for YAML frontmatter and formatting validation |
references/best-practices-checklist.md |
Rules for scoping, specificity calibration, and token budgeting |
references/description-guide.md |
Guidelines for imperative framing and concrete triggering keywords |
references/common-issues.md |
Catalog of known anti-patterns (e.g., Vague Verb Syndrome) |
scripts/audit_skill.py |
Executable script for programmatic Specification (Dimension 1) validation |
assets/report-template.md |
Markdown template used to output severity-ranked findings |
Report Output Format
When an audit is complete, a report is generated containing:
- Findings: Severity, Dimension, and concrete evidence statements.
- Proposed Edits: Standard git-style diffs showing proposed changes.
- Effort Estimate: Difficulty of implementation (trivial edit, refactor, rewrite).
Skill Optimizer Advanced Features
- Three-Dimensional Audit Pipeline: Seamlessly transitions from binary spec validation to nuanced best-practice heuristics and trigger optimization.
- Anti-Pattern Diagnostics: Programmatically flags systemic skill issues like 'vague verb syndrome', 'kitchen-sink skills', and 'tutorializing'.
- Automated Backup & Diffing: Generates workspace snapshots of original files to allow secure reversion and clean code diff reviews.
- Seamless Skill-Creator Hand-off: Integrates with robust test harnesses and evaluation pipelines by passing finalized assets to interactive evaluation systems inside Openclaw Skills.
SKILL.md
Loading
Related Openclaw Skills
CleanShot Skill for OpenClaw
An OpenClaw workflow skill that enables AI agents to coordinate screen captures, OCR, screen recordings, and annotations using the CleanShot Tool plugin.
Dev Guardrails
A universal behavior and guardrail layer for AI coding agents that enforces engineering discipline, prevents scope creep, and guarantees production-viable code quality.
The Creative Act
An executable toolkit modeled on Rick Rubin's creative philosophy to help creators overcome blocks, tune into inspiration, and cultivate a creative mindset.
The Creative Habit
An executable AI-driven toolkit based on Twyla Tharp's philosophy to transform creativity from a mystical whim into a repeatable daily discipline.
The Coddling of the American Mind
An AI-powered cognitive toolkit that implements the behavioral science and psychological principles from Greg Lukianoff and Jonathan Haidt's book to foster resilience, combat cognitive distortions, and build antifragility.
The Butchering Art
An executable AI toolkit based on Lindsey Fitzharris's The Butchering Art, extracting historical lessons from Joseph Lister's quest to reform Victorian medicine.
Featured*
