Skill Standardization

When to use this skill

Creating a new SKILL.md from scratch
Auditing an existing skill for Agent Skills spec compliance
Repairing weak trigger descriptions or stale route-outs
Canonicalizing duplicate skills into a default skill plus compatibility alias
Validating repo-level discovery/catalog drift after add/rename/remove/alias work
Reviewing SKILL.toon / SKILL.compact.md drift after material rewrites

Instructions

Step 1: Pick the smallest working mode

Use references/working-modes.md and pick exactly one primary mode:

validate or repair one existing skill
create or rewrite a SKILL.md
canonicalize duplicates
structural catalog / discovery sync
derived-surface sync after a material rewrite

Do not start with a giant blended pass if one of those modes answers the job.

Step 2: Run the truthful validator command for the current working directory

For oh-my-skills repo-root maintenance loops, use:

bash .agent-skills/skill-standardization/scripts/validate_skill.sh .agent-skills/<skill-name>

If you are running from inside .agent-skills/skill-standardization, use the skill-local form from references/working-modes.md instead. Do not copy bare scripts/... commands into repo-root runbooks unless the current cwd really makes them valid.

The validator checks:

required frontmatter (name, description)
directory-safe naming
description length and imperative trigger phrasing
recommended sections
file-length warning

Repo-specific validator nuance:

validate_skill.sh is expected to accept valid multiline description: > blocks that contain ordinary apostrophes or shell-like text. If it still fails on prose-level quoting, treat that as a validator bug to repair, not as a reason to weaken the skill description.
Prefer fixing the validator or adding a regression case before rewriting natural language just to appease shell parsing.

Step 3: Fix or write the primary `SKILL.md`

When creating or rewriting the skill:

keep the description trigger-oriented and specific about when to use the skill
make the default job-to-be-done obvious before listing edge cases
keep the front door routing-first; move slower-changing examples/checklists/templates to references/ when they start to crowd the main skill
keep SKILL.md under 500 lines and preferably much smaller when the skill is a high-frequency router

Use the compact template and legacy heading map in references/working-modes.md instead of copying a bloated starter by hand.

Step 4: Improve description quality before polishing anything else

A weak description means the skill never activates. Use this pattern:

description: >
  [What it does — list specific operations.]
  Use when [trigger conditions]. Even if the user does not explicitly
  mention [domain keyword] — also triggers on: [synonym list].

Description rules:

use imperative phrasing — "Use when..."
describe user intent, not internal implementation
include edge triggers and nearby synonyms
stay under 1024 characters
keep route-outs truthful when adjacent skills should win

Step 5: Add evals whenever the behavior changed materially

Create or refresh evals/evals.json when you add a skill, rewrite its trigger surface, or narrow it into an alias.

Good eval coverage includes:

a normal prompt that should clearly trigger the skill
a near-miss prompt that should route elsewhere
a structural-change prompt that checks catalog/discovery sync when relevant
compact/discovery-surface checks when SKILL.toon / SKILL.compact.md matter in the repo

Keep assertions concrete and verifiable.

Step 6: Canonicalize duplicates instead of letting them compete

When two skills cover the same default job closely enough that their name + description metadata competes:

pick the canonical skill
sharpen the canonical description so it wins ordinary prompts
convert the overlapping skill into a narrow compatibility alias when old workflows or exact-name installs still depend on it
add evals for both sides
sync discovery surfaces in the same change so users do not see two false peers
if the alias includes support docs or examples that restate the canonical contract, refresh those alias-side docs too so they do not keep advertising the pre-ratchet packet shape

Hard deletion is usually a later step, not the first move.

Step 7: Run structural catalog sync after add / rename / remove / alias / major repositioning work

For repo-level drift in oh-my-skills, use:

python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /Users/jang_jennie/projects/oh-my-skills

Portable form:

python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /path/to/repo

Treat the catalog validator as a guardrail, not the whole job. It checks membership/count/path drift, but it does not replace manual review of derived discovery wording or compact freshness.

Step 8: Sync derived discovery surfaces when the rewrite was material

If SKILL.md changed the job-to-be-done, route-outs, or supported use-cases materially, review and refresh as needed:

skill-local SKILL.toon / SKILL.compact.md
alias-side support docs or checklists that mirror the canonical contract
.agent-skills/skills.json
.agent-skills/skills.toon
README.md
README.ko.md
setup-all-skills-prompt.md

If one of those surfaces does not need a change, be able to explain why.

Step 9: Do a residue scan before calling the pass done

After support-heavy or structural rewrites, search for obvious residue:

stale filenames or paths
removed command examples
old canonical-vs-alias wording
compact/discovery text that still advertises the old job

Keep the pass only if the result is more truthful and transferable than the baseline.

Available scripts

bash .agent-skills/skill-standardization/scripts/validate_skill.sh <skill-dir> — validate one skill
bash .agent-skills/skill-standardization/scripts/validate_skill.sh --all .agent-skills/ — batch validation
python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /path/to/repo — compare live folders against catalog/discovery surfaces
bash .agent-skills/skill-standardization/scripts/regression_folded_description_quotes.sh [repo-root] — regression-check folded descriptions with apostrophes / shell-like text

Examples

Example 1: Validate one skill from repo root

bash .agent-skills/skill-standardization/scripts/validate_skill.sh .agent-skills/my-skill

Example 2: Batch validate the whole repo

bash .agent-skills/skill-standardization/scripts/validate_skill.sh --all .agent-skills/

Example 3: Check catalog/discovery sync after a rename or alias change

python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /path/to/repo

Use this after adding, renaming, removing, or canonicalizing a skill so stale manifest entries, wrong inventory counts, and forgotten derived-surface updates do not linger.

Example 4: Fix common frontmatter issues

# WRONG
metadata:
  tags: [tag1, tag2]
  platforms: Claude

# CORRECT
metadata:
  tags: tag1, tag2
allowed-tools: Bash Read Write

Best practices

Description quality first — weak descriptions mean the skill never activates
Shrink high-frequency routers — move slower-changing detail to references/ before the front door turns into a handbook
Use truthful command paths — match repo-root vs skill-local execution context explicitly
Keep scripts non-interactive and structured — prefer flags and machine-readable output
Add evals before publishing — cover should-trigger, should-not-trigger, and structural-change cases
Treat compact/discovery files as derived artifacts — refresh them after material rewrites or document why not
Canonicalize duplicates instead of multiplying peers — prefer one default skill plus a compatibility alias
Sync alias-side support when the canonical contract changes — if the alias has checklists, references, or examples that restate the old packet shape, update them in the same pass so the alias does not quietly preserve stale guidance
Run residue scans after structural rewrites — passing validators can still leave stale filenames, commands, or discovery copy behind

skill-standardization