# Skill Standardizer > Use when skill copies drift across repositories or agent globals and you need canonicalization, drift auditing, and safe synchronization across local and global skills directories. - Skill: `davisbuilds/skill-standardizer` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add davisbuilds/skill-standardizer` - Raw SKILL.md: https://api.skillmd.com/api/skills/davisbuilds/skill-standardizer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: davisbuilds (https://skillmd.com/u/davisbuilds) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/davisbuilds/skill-standardizer --- # 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/` is relinked to `~/.agents/skills/` 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 ` 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 ` 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 ` to apply only the selected skill's planned changes. - Use `--ignore-dir ` 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 `** — 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 ```bash python3 /scripts/discover.py ``` ### 2) Audit (dry run) ```bash python3 /scripts/audit.py \ --global-policy prefer-primary-link \ --format text ``` Optional JSON report: ```bash python3 /scripts/audit.py \ --format json \ --report-out /tmp/skill-drift-report.json ``` ### 3) Apply Synchronization ```bash python3 /scripts/sync.py \ --global-policy prefer-primary-link \ --apply ``` ### 4) Verify ```bash python3 /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: ```bash python3 /scripts/sync.py \ --global-policy prefer-primary-link \ --enforce-mirror \ --apply ``` For targeted fixes, scope the operation to the affected skill: ```bash python3 /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. ```bash python3 /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. ```bash python3 /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.