Skill wiring in dotfiles
agents/skills/ is the single source of truth for repo-owned skills. dotfiles.sh
symlinks each into the agent dirs its SKILLS table selects. Run ./dotfiles.sh
after any change to re-sync symlinks.
Editing skills
The root CLAUDE.md/AGENTS.md carries the one rule you must not miss: never edit
in ~/.claude/skills/, ~/.codex/skills/, ~/.grok/skills/, or
~/.pi/agent/skills/ — those are symlinks. Check agents/skills/README.md for source.
- Own skills (
agents/skills/): edit in this repo — the single source of truth. - Third-party skills (cloned from GitHub): edit in the source repo or fork.
- Best practices: read
agents/skills/references/skill-best-practices.mdbefore creating or improving skills. - Description length: every skill's
descriptionfrontmatter must stay under 1024 characters — trim it before committing. - Universal (C/X/G — Claude/Codex/Grok) skills: read
agents/skills/references/universal-skill-authoring.mdbefore editing a skill shared across all these agents — keep the body harness-agnostic (no$ARGUMENTS, no bareAskUserQuestion/Skill(), capability-not-runtime degradation). Pi consumes this same shared set (mirroring the Codex/Grok column), so the harness-agnostic rules apply to it too../dotfiles.shwarns on the mechanical violations;./dotfiles.sh lintruns the check on demand. - Verify vendor guidance: before updating skills with vendor/model guidance, check against official current docs — don't preserve stale model names or deprecated API parameters.
- Validate referenced paths: when skill docs reference installed or symlinked
paths, verify they exist after
./dotfiles.sh.
Adding extensions
Managed by the SKILLS table in dotfiles.sh (local path or GitHub clone +
symlink, no npx skills):
- Local: add
<name>/SKILL.mdunderagents/skills/, run./dotfiles.sh. - Upstream: add a
name|owner/repo/subpath|agentsentry to theSKILLStable. - Agent-specific: separate table entries per agent (e.g.,
pdfhas different sources for claude vs codex/grok). - Manual skills: add the name to the
MANUAL_SKILLSarray — skipped during auto-install, toggled with./dotfiles.sh enable/disable <name>. Enabled state is a committed declarative set inagents/skills/manual-skills.enabled(one name per line; empty = all off), enforced on every run (symlink the listed, prune the rest) and propagated bydfs— not per-machine local. - Project-local skills: place in
.claude/skills/<name>/— available only in this repo, not globally. - Install/update all:
./dotfiles.sh.
A single SKILL.md can work across agents when written harness-agnostically.
Include Claude-specific frontmatter (allowed-tools, user-invocable) where
needed — Codex/Grok ignore unknown keys.
MCP servers and Claude plugins are wired the same way, via the MCP_SERVERS and
PLUGINS tables in dotfiles.sh — see agents/skills/README.md for the full
catalog.
Naming and shape
- Lowercase kebab-case for skill directories (e.g.,
arxiv-reader,keep-warm). - Each skill has a single
SKILL.md; most work across Claude Code, Codex, Grok, and Pi, but theSKILLStable can scope one to specific agents.
Verifying
- Run
./dotfiles.shand confirm symlinks resolve correctly. - Run
./dotfiles.sh lintwhen editing universal skills or skill-install logic. - For skills with Python scripts, run
uv run pyteston the relevant test file.