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.md before
creating or improving skills.
- Description length: every skill's
description frontmatter must stay under
1024 characters — trim it before committing.
- Universal (C/X/G — Claude/Codex/Grok) skills: read
agents/skills/references/universal-skill-authoring.md before editing a skill
shared across all these agents — keep the body harness-agnostic (no $ARGUMENTS,
no bare AskUserQuestion/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.sh warns on the mechanical
violations; ./dotfiles.sh lint runs 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.md under agents/skills/, run ./dotfiles.sh.
- Upstream: add a
name|owner/repo/subpath|agents entry to the SKILLS table.
- Agent-specific: separate table entries per agent (e.g.,
pdf has different
sources for claude vs codex/grok).
- Manual skills: add the name to the
MANUAL_SKILLS array — skipped during
auto-install, toggled with ./dotfiles.sh enable/disable <name>. Enabled state is
a committed declarative set in agents/skills/manual-skills.enabled (one name per
line; empty = all off), enforced on every run (symlink the listed, prune the rest)
and propagated by dfs — 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 the SKILLS table can scope one to specific agents.
Verifying
- Run
./dotfiles.sh and confirm symlinks resolve correctly.
- Run
./dotfiles.sh lint when editing universal skills or skill-install logic.
- For skills with Python scripts, run
uv run pytest on the relevant test file.
1---2name: skill-wiring3description: How this dotfiles repo wires skills, MCP servers, and Claude plugins — where to edit each kind of skill, the SKILLS/MCP_SERVERS/PLUGINS tables in dotfiles.sh, manual-skill toggling, and the authoring rules for universal (Claude/Codex/Grok/Pi) skills. Use when adding, editing, moving, scoping, enabling, or disabling a skill, MCP server, or plugin in this repo, or when a skill's symlink or agent targeting looks wrong.4---56# Skill wiring in dotfiles78`agents/skills/` is the single source of truth for repo-owned skills. `dotfiles.sh`9symlinks each into the agent dirs its `SKILLS` table selects. Run `./dotfiles.sh`10after any change to re-sync symlinks.1112## Editing skills1314The root `CLAUDE.md`/`AGENTS.md` carries the one rule you must not miss: never edit15in `~/.claude/skills/`, `~/.codex/skills/`, `~/.grok/skills/`, or16`~/.pi/agent/skills/` — those are symlinks. Check `agents/skills/README.md` for source.1718- **Own skills** (`agents/skills/`): edit in this repo — the single source of truth.19- **Third-party skills** (cloned from GitHub): edit in the source repo or fork.20- **Best practices**: read `agents/skills/references/skill-best-practices.md` before21 creating or improving skills.22- **Description length**: every skill's `description` frontmatter must stay under23 1024 characters — trim it before committing.24- **Universal (C/X/G — Claude/Codex/Grok) skills**: read25 `agents/skills/references/universal-skill-authoring.md` before editing a skill26 shared across all these agents — keep the body harness-agnostic (no `$ARGUMENTS`,27 no bare `AskUserQuestion`/`Skill()`, capability-not-runtime degradation). Pi28 consumes this same shared set (mirroring the Codex/Grok column), so the29 harness-agnostic rules apply to it too. `./dotfiles.sh` warns on the mechanical30 violations; `./dotfiles.sh lint` runs the check on demand.31- **Verify vendor guidance**: before updating skills with vendor/model guidance,32 check against official current docs — don't preserve stale model names or33 deprecated API parameters.34- **Validate referenced paths**: when skill docs reference installed or symlinked35 paths, verify they exist after `./dotfiles.sh`.3637## Adding extensions3839Managed by the `SKILLS` table in `dotfiles.sh` (local path or GitHub clone +40symlink, no `npx skills`):4142- **Local**: add `<name>/SKILL.md` under `agents/skills/`, run `./dotfiles.sh`.43- **Upstream**: add a `name|owner/repo/subpath|agents` entry to the `SKILLS` table.44- **Agent-specific**: separate table entries per agent (e.g., `pdf` has different45 sources for claude vs codex/grok).46- **Manual skills**: add the name to the `MANUAL_SKILLS` array — skipped during47 auto-install, toggled with `./dotfiles.sh enable/disable <name>`. Enabled state is48 a committed declarative set in `agents/skills/manual-skills.enabled` (one name per49 line; empty = all off), enforced on every run (symlink the listed, prune the rest)50 and propagated by `dfs` — not per-machine local.51- **Project-local skills**: place in `.claude/skills/<name>/` — available only in52 this repo, not globally.53- **Install/update all**: `./dotfiles.sh`.5455A single `SKILL.md` can work across agents when written harness-agnostically.56Include Claude-specific frontmatter (`allowed-tools`, `user-invocable`) where57needed — Codex/Grok ignore unknown keys.5859MCP servers and Claude plugins are wired the same way, via the `MCP_SERVERS` and60`PLUGINS` tables in `dotfiles.sh` — see `agents/skills/README.md` for the full61catalog.6263## Naming and shape6465- Lowercase kebab-case for skill directories (e.g., `arxiv-reader`, `keep-warm`).66- Each skill has a single `SKILL.md`; most work across Claude Code, Codex, Grok, and67 Pi, but the `SKILLS` table can scope one to specific agents.6869## Verifying7071- Run `./dotfiles.sh` and confirm symlinks resolve correctly.72- Run `./dotfiles.sh lint` when editing universal skills or skill-install logic.73- For skills with Python scripts, run `uv run pytest` on the relevant test file.
chrisliu298