dotfiles-skill-linter

name	dotfiles-skill-linter
description	Audit and repair skills managed by this dotfiles repo for Agent Skills metadata, naming, progressive-disclosure limits, and global discovery across generic agents, Claude Code, and Codex. Use when adding or changing a skill, checking machine setup, diagnosing a missing skill, or asking to lint, sync, link, distribute, or audit skills.

Lint and sync dotfiles skills

Treat .agents/skills/ as the canonical, vendor-neutral source for skills, and AGENTS.md as the canonical repo instruction file. Do not maintain copies under client-specific directories beyond the required compatibility shims.

Audit

From the dotfiles repository root, run:

scripts/maintenance/sync-agent-skills.sh

Report every failure and warning. The command validates canonical SKILL.md metadata and Codex agents/openai.yaml interface metadata, checks the AGENTS.md/CLAUDE.md instruction arrangement, and confirms that each repo skill resolves from these user-level discovery roots:

• ~/.agents/skills
• ~/.claude/skills
• ${CODEX_HOME:-~/.codex}/skills

From a secondary worktree, live discovery links are expected to resolve to the canonical checkout and therefore appear as mismatches. Do not repair those links from the worktree; use scripts/ci_checks.sh for its temporary-HOME discovery test, and run the live audit again from the canonical checkout after the change is merged.

Also run the current Codex validator against every canonical skill when both the script and its Python yaml dependency are available:

for skill in .agents/skills/*; do
  python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py "$skill"
done

If either prerequisite is unavailable, report the secondary validator as unavailable; do not modify a client-owned system skill or the global Python interpreter during an audit.

Do not modify third-party or client-owned system skills during an audit. Hunk is the exception to canonical repo ownership: when installed, its bundled hunk-review skill is linked directly from the path reported by hunk skill path, preferring Homebrew's stable opt path. Do not copy that skill into the repo, because Hunk upgrades should update it in place.

Repair

After reviewing the audit, run:

scripts/maintenance/sync-agent-skills.sh --fix

The repair is idempotent. It creates missing discovery directories and links. If a destination is unmanaged, it preserves it as a timestamped backup before creating the link. Each discovery root records repo-managed names in .dotfiles-managed-skills, allowing later audits to detect renamed or removed skills and --fix to prune only obsolete managed symlinks.

Run the read-only audit again, then scripts/bootstrap/verify.zsh when a full machine verification is appropriate. Tell the user that already-running agent sessions may need to restart before newly discovered skill metadata appears.

Add or update a skill

Create skills only in .agents/skills/<skill-name>/. Follow the Agent Skills specification: a lowercase hyphenated directory matching the frontmatter name, a useful description explaining both capability and triggers, and a concise SKILL.md. Put deterministic logic in scripts/, detailed material in references/, and output resources in assets/.

Keep shared project instructions in AGENTS.md. Keep CLAUDE.md as a thin compatibility shim that imports @AGENTS.md; do not duplicate project rules in both files.

Generate or refresh agents/openai.yaml with Codex's skill-creator utilities, validate the skill, run this linter with --fix, and commit the canonical files and any setup-script changes. Never commit generated home-directory links.