skill-standardizer

Standardizes and unifies skills across canonical, global, and local mirrors.

What This Skill Solves

Use this skill when you see recurring problems like:

• multiple copies of the same skill with content drift
• platform-specific logic mixed into core SKILL.md behavior
• local project installs duplicating global installs
• uncertainty about which copy is canonical

This skill provides a deterministic workflow:

1. Discover roots and classify scope.
2. Audit byte-level and semantic drift.
3. Generate actions (dry run by default), including deprecated-name replacement when configured by policy.
4. Apply safe synchronization with backups.
5. Re-audit and report final state.

Canonical Model

Default policy:

• Repository skills/ is canonical when discoverable.
• User global roots are mirrors:
  • ~/.agents/skills
  • ~/.codex/skills
  • ~/.claude/skills
• Plugin caches (for example ~/.claude/plugins/cache) are excluded by default.

If no canonical repo is discoverable from current working directory, operate in global/local audit mode and avoid canonical overwrite actions.

Local vs Global Policy

Default local policy is prefer-global-link:

• If a skill exists both locally and globally, local copy should be replaced with a symlink to the preferred global copy.
• If local differs, back it up before relinking.
• Allow explicit keep-local exceptions when needed.

Default global policy is prefer-primary-link:

• Keep a concrete copy in the primary global root (~/.agents/skills by default).
• Keep secondary globals (~/.codex/skills, ~/.claude/skills) as symlinks to that primary copy.
• This avoids duplicate skill entries in clients that aggregate multiple global roots.
• Use --global-policy mirror-copy when fully independent per-global copies are required.

Codex/Agents dedupe guard (enabled by default):

• --codex-agents-dedupe keeps ~/.agents/skills authoritative for Codex-facing catalogs.
• When enabled, ~/.codex/skills/<skill> is relinked to ~/.agents/skills/<skill> to avoid duplicate entries in Codex dropdowns.
• Use --no-codex-agents-dedupe only if you explicitly need separate Codex copies.

Preferred global precedence:

1. ~/.agents/skills
2. ~/.codex/skills
3. ~/.claude/skills

Rename Policy

Deprecated skill names can be mapped to canonical replacements.

Current built-in mapping:

• json-canvas -> obsidian-canvas
• imagegen -> gpt-imagen

When a deprecated skill name is found:

• audit should report it explicitly instead of treating it as an unrelated extra directory
• sync should back up the deprecated copy, install the canonical replacement in the same root, and remove the old name
• secondary globals and local duplicates should still follow the normal link/copy policy for the replacement skill

Scripts

Run from anywhere; scripts auto-discover repo root when possible.

• scripts/discover.py
  • Resolves canonical root, target roots, and discovered skills.
• scripts/audit.py
  • Detects drift and emits a JSON report plus readable summary.
  • Use --skill <name> to limit planning to one skill; repeat for multiple skills.
  • Exit codes: 0 no drift, 2 drift found (one or more actions planned), 1 error.
  • Warning-level issues that plan no action (for example an unrecognized non-skill directory) are reported but do not change the exit code.
  • Use --ignore-dir <name> to treat a directory as a non-skill support dir; repeat for multiple names.
• scripts/sync.py
  • Applies planned actions (copy/symlink) with backups.
  • Use --skill <name> to apply only the selected skill's planned changes.
  • Use --ignore-dir <name> as with audit.py.
  • Default is dry run; use --apply to execute.

Non-Skill Directories

A directory inside a skills root that has no SKILL.md is normally reported as INVALID_SKILL_DIR — or as DANGLING_SKILL_LINK when the entry is a symlink whose target no longer exists, since that is repaired by recreating the link rather than by authoring a file. Three kinds are exempt:

• Underscore-prefixed (skills/_fragments) — the convention for support directories this repo owns. Preferred for anything you control.
• Known tool-owned dirs — KNOWN_NON_SKILL_DIRS in scripts/skill_standardizer_lib.py, keyed by root kind so an exemption cannot leak into a root it was not meant for. codex-primary-runtime in ~/.codex/skills is exempt this way: Codex owns that path, so it cannot be renamed to the underscore convention.
• --ignore-dir <name> — ad-hoc, for a directory you cannot rename and that is not worth a built-in entry.

Add a built-in entry when a directory is permanent and tool-owned; use the flag otherwise.

Standard Workflow

1) Discover

python3 <skill-dir>/scripts/discover.py

2) Audit (dry run)

python3 <skill-dir>/scripts/audit.py \
  --global-policy prefer-primary-link \
  --format text

Optional JSON report:

python3 <skill-dir>/scripts/audit.py \
  --format json \
  --report-out /tmp/skill-drift-report.json

3) Apply Synchronization

python3 <skill-dir>/scripts/sync.py \
  --global-policy prefer-primary-link \
  --apply

4) Verify

python3 <skill-dir>/scripts/audit.py \
  --global-policy prefer-primary-link \
  --format text

Fix Duplicate Global Skill Entries

When a skill appears multiple times in a client catalog, normalize globals to primary+links:

python3 <skill-dir>/scripts/sync.py \
  --global-policy prefer-primary-link \
  --enforce-mirror \
  --apply

For targeted fixes, scope the operation to the affected skill:

python3 <skill-dir>/scripts/sync.py \
  --skill api-design \
  --global-policy prefer-primary-link \
  --enforce-mirror \
  --apply

--skill is repeatable. In selected-skill mode, audits and sync plans hide unrelated invalid directories and unrelated canonical skills. Deprecated aliases remain in scope when either the alias or replacement is selected.

Intersection Mode

Use --only-existing to restrict canonical sync to skills already installed in target roots. This prevents adding new skills that happen to exist in the canonical repo but were never installed globally.

python3 <skill-dir>/scripts/sync.py \
  --only-existing \
  --global-policy prefer-primary-link \
  --apply

Topology Normalization

Use --normalize-primary to promote concrete skills from secondary globals (~/.codex/skills, ~/.claude/skills) to the primary global root (~/.agents/skills) and replace the secondary copies with symlinks. This is useful when skills were originally installed in a secondary root and need to be consolidated.

python3 <skill-dir>/scripts/sync.py \
  --normalize-primary \
  --global-policy prefer-primary-link \
  --apply

Safety Rules

• Never mutate plugin cache directories unless explicitly included.
• Never overwrite without backup in apply mode.
• Never remove a deprecated skill name without creating or confirming the canonical replacement in that root.
• Always print resolved canonical and target roots before applying.
• If no canonical root is found, restrict apply actions to explicit local/global normalization.

Notes On Portability

Keep core policy and decision logic model-agnostic in SKILL.md and scripts. Platform-specific command syntax or orchestration belongs in optional wrappers or references.

See references/policy.md for policy details and tradeoffs.

When To Use

• When skill copies drift across repository, global, and local directories
• When duplicate skill entries appear in agent client catalogs
• When uncertainty exists about which copy of a skill is canonical
• After adding or updating skills that exist in multiple roots

Output

• A drift audit report (text or JSON) listing all discovered skills and their sync status
• Backup copies of any files replaced during synchronization
• Symlinks replacing duplicate copies to point at the canonical or primary source

Verification

• Post-sync audit exits with code 0 (no drift remaining). Remaining warning-level issues about non-skill directories are informational and do not fail this check.
• All symlinks resolve to valid targets
• No plugin cache directories were mutated unless explicitly included
• Canonical and target roots are printed before any apply operation

Sibling skills

Part of the skill-management toolchain (maintenance).

• skill-installer — common upstream. Use this skill after installing across multiple agent homes to consolidate copies.
• skill-evals — run after sync to confirm copies still pass the contract.
• find-skills — discovery. Orthogonal to drift management.