batch-skill-description-standardization

Batch Skill Description Standardization

When to Use This Skill

When you need to update descriptions across 20+ SKILL.md files with a consistent pattern (e.g. converting all to "Use when..." format).

The Problem

An agent skills directory can have 160+ SKILL.md files with inconsistent descriptions. Some describe workflow instead of triggering conditions. Some start with verbs. Some are 80+ words long. Patching them one-by-one uses 100+ tool calls and is prone to error.

The Superpowers Insight (CSO)

From superpowers' "Claude Search Optimization" analysis:

• If description summarizes workflow, the agent follows the description and SKIPS the skill body.
• Description should ONLY describe WHEN to use, NEVER WHAT the skill does.
• Format: "Use when [precise triggering condition]."

The Workflow

Step 1: Scan and classify

from hermes_tools import search_files, read_file
import re

result = search_files(pattern='SKILL.md', target='files', path='/path/to/skills', limit=200)
files = result['files']

Check each SKILL.md's description line for three problems:

1. Doesn't start with "Use when" — most common
2. Describes workflow (has words like "步驟", "流程", "phase", "checklist", "step 1")
3. Too long (over 80 words)

Step 2: Handle the two YAML description formats

There are TWO formats for description in SKILL.md frontmatter:

Format A — Single line:

description: Some text here.

Format B — Folded multiline (uses > or >-):

description: >
  Long text that spans
  multiple lines in the file
  but becomes one line in YAML.

CRITICAL: For Format B, you CANNOT just replace the description line. You must replace the ENTIRE block from description: to the next YAML key.

Step 3: Write the batch script

Build a Python dict mapping skill identifiers to new descriptions. Use a script with re.sub() to find and replace:

pattern = r'(description:\s*)(.+?)(?=\n(?:---|name:|version:|author:|title:|tags:|category:|metadata:|last_|created:|related|triggers|license:|  )|\Z)'
replacement = f'description: {new_desc}'
new_content = re.sub(pattern, replacement, content, count=1, flags=re.DOTALL)