Maintain Dot Skills

Maintain first-party skills and their chezmoi links. skillify owns authoring; its package rules define package shape, resources, and standalone portability.

Workflow

1. Choose the owner: inspect git diff and git diff --cached, read neighboring descriptions, and apply skillify's admission rule. Reusable skills belong in skills/; repository procedures belong in .agents/skills/.
2. Register additions: each scope (AGENTS.md plus skill names, descriptions, and paths) must stay below 5,000 estimated tokens per context budgets; mise run check:skills enforces both scopes from source. Check headroom first with dot agent context --source . --project . and reduce overhead without losing distinctive triggers when full; an addition with under about 60 tokens of global headroom must free an index entry (merge or remove a skill) in the same change. Each global skill needs dot_agents/skills/symlink_<name>.tmpl containing {{ .chezmoi.sourceDir }}/skills/<name>.
3. Connect resources: use metadata.kind as the single connector, task, or collection tag. Keep a single procedure in the root; preserve substantial optional modes as guides at references/<name>.md or references/<name>/GUIDE.md, with their owned resources. Run mise run format:skills to generate parent routing indexes. Never nest SKILL.md. Update project AGENTS.md when workflow ownership changes; setup, usage, and the short task reference belong in README.md.
4. Validate: run mise run check:skills and formatting checks for edited files. For installation changes, also target uv run --frozen --project dot pytest -q dot/tests/test_skill_install_links.py. Follow project AGENTS.md for broader qualification; prose-only changes do not require the full Python suite or build. Use git-worktree when formatters could alter unrelated work. dot agent context --check without --source also measures independently installed packages in the shared roots. Review dot agent context --source . --project . --details when descriptions or guides change; its estimates are diagnostic.
5. Exercise changed guidance per skillify; when host integration changes, check the affected host separately, since catalog checks do not prove discovery or selection.

Rename or remove

1. Locate references; rename atomically: use rg to find the old name and path across both catalogs, docs, host configuration, and dot/. For a rename, change the directory, frontmatter name, provenance path, and update date together; preserve needed guidance when consolidating packages.
2. Repoint all links at once: update inbound links and the global link declaration together. Preserve historical records, then search again and validate as above.
3. Retire installed links with .chezmoiremove: list the retired .agents/skills/<name> targets there so apply deletes them on every machine, per the chezmoi skill. Use the installed-link recovery guide for manual cleanup or source relocation.

Boundaries

• Keep ~/.agents/skills/ a real shared directory: never exact_ or a whole-catalog symlink. Independently installed packages remain outside this repository; names must be unique, and apply rejects a name owned elsewhere: choose another name instead of overwriting that package.
• Know each check's coverage: mise run check:skills validates both first-party roots; gh skill publish --dry-run skills alone covers only the global directory. Sibling references are allowed here; standalone publication needs the package rules' portability check.

Documentation

• skill_contracts.py enforces package shape, resources, guide indexes, and context budgets; contract tests cover it and chezmoi link registration; lychee checks Markdown links.
• Companion skills: agent-project (host discovery), repository-docs (documentation ownership).