Skill YAML Cleanup

Skill YAML Cleanup

Author: jovd83 | Version: 2.0.0 | License: MIT

Audit and optimize YAML frontmatter in SKILL.md files. Agent platforms enforce a 1,000-character limit on frontmatter blocks. Exceeding this causes preloading failures and context overflow. This skill finds, analyzes, and — with your approval — fixes oversized blocks.

When to Trigger

• User says "clean up skill metadata", "frontmatter is too long", "reduce YAML bloat", or "audit skills"
• Skills are failing to preload or causing context overflow
• New metadata fields were added and may have exceeded the limit
• Auditing or migrating a skill registry

Workflow

Follow these phases in order. Never modify files before the approval gate in Phase 3.

Phase 1 — Audit

Scan the skills directory and report all oversized frontmatter blocks:

python scripts/audit.py --dir <skills_directory>

Report to the user:

• Total skills scanned
• Total over the 1,000-char limit
• Grouped by severity: Critical (>1,300), Warning (1,100–1,300), Tolerable (1,000–1,100)

Use --json for structured output when chaining with other tools.

Phase 2 — Analyze and Propose

For each oversized skill, determine which optimizations apply:

python scripts/analyze.py --file <path/to/SKILL.md>

Present a before/after diff for each proposed change:

Skill: release-manager-skill  (1,524 → ~970 chars, saves 554)
Actions: field-migration, description-trim, flattening

BEFORE description:
  "Validate and prepare GitHub releases following SemVer and CHANGELOG standards. Trigger to: ..."

AFTER description:
  "Validate and prepare GitHub releases. Trigger for: SemVer changelogs, version bumps, release commits, CI/CD monitoring, and repo bootstrap."

Fields to REMOVE from frontmatter (moved to body):
  license, compatibility, author, version, maturity

Do not apply changes yet. Present the full proposal and ask: "Shall I apply these changes?"

Phase 3 — Approval Gate (mandatory)

Wait for explicit user confirmation. This is a hard stop.

• Yes to all: proceed to Phase 4
• Yes to some: apply only the approved skills/optimizations
• No: stop — no files are modified

Phase 4 — Apply

Apply approved changes using the bundled scripts. Run in this order per skill:

1. scripts/deduplicate.py --file <path> --backup — merge duplicate metadata blocks
2. scripts/flatten.py --file <path> — convert vertical lists to inline values
3. scripts/remove_noise.py --file <path> — strip noise/decorative fields
4. scripts/migrate_to_body.py --file <path> — move non-dispatcher fields to body
5. Manual description trim (if approved) — edit the description: value directly

Always use --backup on the first script to create a .bak safety copy. Subsequent scripts operate on the already-backed-up file.

Use --dry-run on any script to preview without writing.

Phase 5 — Verify

Re-run the audit on modified files only:

python scripts/audit.py --dir <skills_directory> --files <changed_file1> <changed_file2>

Report the final result:

• ✅ Skills now clean (≤ 1,000 chars)
• ⚠️ Skills still over (and by how much)

If any skill remains over after all safe optimizations, report it as requiring manual description editing and show the user the exact line to trim.

Alternative: Unified Pipeline

For convenience, all phases can be run through a single command:

python scripts/cleanup.py --dir <skills_directory> --analyze --apply --backup --dry-run

Remove --dry-run to apply changes. The unified CLI still requires the agent to present results and obtain approval before the --apply phase.

Frontmatter vs. Body Contract

Stays in frontmatter (dispatcher reads these)

name, description, all metadata.dispatcher-* keys

Moves to body (agent reads the full file)

license, compatibility, author, version, maturity, homepage, platforms

The agent reads the entire SKILL.md — moving fields to the body loses nothing. The dispatcher preloader only reads the frontmatter block.

Migrated metadata format in body:

> **Author:** jovd83 | **Version:** 2.0.0 | **License:** MIT
> **Compatibility:** Requires Python 3.10+

Guardrails

• Never apply without approval. The Phase 3 approval gate is mandatory and non-negotiable.
• Never trim dispatcher-* keys. These are the routing contract. Only shorten values where safe.
• Preserve semantic meaning. When shortening descriptions or capability values, keep all trigger keywords. Do not remove domain terms that help the dispatcher match the skill.
• Do not over-abbreviate intents. prepare_release is acceptable; prep_rel is not.
• Always use --backup on the first write to a file. If something goes wrong, the .bak file provides recovery.
• Use --dry-run first when uncertain about the impact of an optimization.

Scripts Reference

Optional Integration: Telemetry

If your environment uses a skill dispatcher with telemetry logging, log usage after each invocation:

./log-dispatch.cmd --skill skill-yaml-cleanup --intent <intent> --model <model> --reason <reason>

This is optional and depends on your infrastructure setup.