skill-improver

Audit and refactor SKILL.md files against an LLM-first style guide.

Updated Aug 25, 2026
One-click install
npx skills add https://github.com/CarlosWilliamsR/SketchOS --skill skill-improver-carloswilliamsr
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: skill-improver
Source: https://github.com/CarlosWilliamsR/SketchOS/tree/main/.config/opencode/skills/skill-improver
Command: npx skills add https://github.com/CarlosWilliamsR/SketchOS --skill skill-improver-carloswilliamsr

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Existing SKILL.md files often drift from the required structure: missing frontmatter, bloated bodies, prose-heavy branching, or unclear triggers. This Skill audits and refactors them against a normative LLM-first style guide without losing author intent. ## Core Features & Use Cases - Structured Audits: Checks frontmatter completeness, trigger clarity, section order, body token budget, decision gates, and output contracts for each skill. - Safe Refactoring: Defaults to audit-only mode and only edits files when explicitly asked, moving long explanations into local references instead of deleting content. - Registry Awareness: Uses .atl/skill-registry.md to locate skills and recommends a registry refresh when metadata or paths change. - Use Case: You maintain a repository of agent skills and want a severity-grouped report of every SKILL.md that violates the style guide, plus safe automatic fixes for frontmatter and structure issues. ## Quick Start Audit all skills in this repository against the skill style guide and report issues grouped by severity.

Frequently Asked Questions about skill-improver

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit SKILL.md files for style guide compliance?

Run the skill-improver audit workflow: it reads the style guide, locates skills via the registry or directory scan, and checks frontmatter, section order, body budget, and decision gates. Results are returned grouped by skill and severity.

How to refactor a bloated SKILL.md without losing content?

Move long explanations, examples, and schemas into local references/ or assets/ files while keeping hard rules and activation semantics in SKILL.md. The skill never deletes meaningful content silently and marks ambiguous rules for human review.

Does skill-improver modify files automatically?

No, it defaults to audit-only mode. Files are edited only when the user explicitly requests apply mode, and even then only safe issues are fixed while preserving author intent and critical rules.

What happens when the skill style guide is missing?

The skill falls back to a bundled local copy in references/skill-style-guide.md. If neither exists, it enforces the core LLM-first structure: frontmatter, Activation Contract, Hard Rules, Decision Gates, Execution Steps, Output Contract, and References.

When should I use skill-creator instead of skill-improver?

Use skill-creator when building a brand-new skill from a reusable pattern. Use skill-improver only when auditing, normalizing, or refactoring existing SKILL.md files that already contain author intent worth preserving.