skill-improver

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

Updated Mar 7, 2026
One-click install
npx skills add https://github.com/albersg/dotfiles --skill skill-improver-albersg
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: skill-improver
Source: https://github.com/albersg/dotfiles/tree/main/dotfiles-opencode/.opencode/skills/skill-improver
Command: npx skills add https://github.com/albersg/dotfiles --skill skill-improver-albersg

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, tutorial-style prose, oversized bodies, or unclear triggers. This Skill audits and upgrades those files so they remain discoverable and executable as runtime instructions for LLM agents. ## Core Features & Use Cases - Structured Auditing: Checks frontmatter completeness, trigger clarity, section order, body token budget, decision gates, and output contracts against the skill style guide. - Safe Refactoring: Defaults to audit-only mode and only edits files when explicitly asked, preserving author intent and moving long content into references/ or assets/. - Registry Awareness: Uses .atl/skill-registry.md to locate skills and recommends a registry refresh when metadata or paths change. - Use Case: After adding several custom skills to a repository, run an audit to find skills with invalid frontmatter or bloated bodies, then apply fixes that convert prose branching into decision tables. ## 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, which reads the style guide, locates skills via .atl/skill-registry.md or by scanning for SKILL.md files, and returns a report grouped by skill with severity levels and exact proposed changes.

What structure should a SKILL.md file follow?▼

A SKILL.md should contain frontmatter, an Activation Contract, Hard Rules, Decision Gates, Execution Steps, an Output Contract, and References, in that order. The body should target 180-450 tokens with a hard maximum of 1000 tokens.

Does the skill audit 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 meaningful content is preserved or moved into references/ or assets/.

What happens when a skill body exceeds the token budget?▼

The improver preserves the core rules and moves examples, background, templates, or schemas into local references/ or assets/ directories. Long explanations are never deleted silently.

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, refactoring, normalizing, or upgrading existing SKILL.md files.