Skills and Plugins

A skill is a SKILL.md file of instructions (a procedure, a checklist, the gotchas) that an agent loads only when the task calls for it. A plugin packages skills together with hooks, MCP servers, language servers and command-line tools into one unit you install with one command. Skills are where most of Cole’s hard-won knowledge lives: how to park a session, how to fan out to worktrees, how to read a Codex transcript, how to hand off. Cole publishes them as a public plugin marketplace, dx, and keeps one copy of every skill shared by Claude Code and Codex on every machine.

Skills

A skill is a directory with a SKILL.md and, optionally, scripts and reference files beside it. A minimal one (a made-up example) looks like this:

---
name: release-notes
description: Draft release notes from the commits since the last tag. Use when the user says "write the release
  notes", "what changed since the last release", or before tagging a version.
---

# release-notes

1. Find the last tag with `git describe --tags --abbrev=0`.
2. Group the commits since it by Conventional Commit type.
3. Write one line per user-visible change; skip chores.

The description is what matters most. Every turn, the model sees the list of skills with their descriptions, and decides from the description alone whether to load one; the body loads only when the skill runs. So a long reference costs almost nothing until it is needed. You can also run a skill directly by name, as /release-notes.

Where	Path	Loads in
Personal	~/.claude/skills/<name>/SKILL.md	All your projects on this machine
Project	.claude/skills/<name>/SKILL.md	Sessions in that repository; commit it for your team
Plugin	<plugin>/skills/<name>/SKILL.md	Wherever the plugin is enabled, as /plugin-name:skill-name

A personal skill wins over a project skill of the same name. A few frontmatter fields change behavior: disable-model-invocation: true makes a skill run only when you type it, and allowed-tools pre-approves tools for the turn that invokes it. Claude Code’s skills follow the Agent Skills open standard, which is why the same file works in other tools.

The listing has a budget: by default Claude Code gives skill descriptions 1% of the context window and drops the descriptions of the least-used skills past it. With dozens of skills installed, Cole raises it to 2% (skillListingBudgetFraction: 0.02), so the model still knows what each one is for.

Plugins

A plugin is a directory with a manifest at .claude-plugin/plugin.json and any of these components:

• skills and agents (subagent definitions);
• hooks, which run at lifecycle events while the plugin is enabled (see Hooks);
• MCP servers and language servers, started alongside each session (see MCP and Language Servers);
• a bin/ directory, which Claude Code puts on the Bash tool’s PATH while the plugin is enabled, so a skill can call its own CLI by name with nothing else installed.

Plugins come from marketplaces: a repository with a .claude-plugin/marketplace.json that lists plugins and where to fetch each. Anthropic’s official marketplace is added automatically; any other is added by its GitHub name:

/plugin marketplace add coletebou/dx
/plugin install worktrees@dx
/plugin                       # browse, enable, disable

A plugin installs at user scope (every project), project scope (everyone in the repository, through committed settings) or local scope (you, in this repository only). An enabled plugin is part of every session, not only the ones that use it: its skills’ descriptions take context on every turn, its MCP servers run as processes, its hooks fire, and everything it runs, runs as you. Read a plugin before you trust it.

Cole’s marketplace

Plugin	Skills	What they do
session	cc-park, fresh-session-handoff	Park idle sessions; hand a long session to a fresh one (cc-park, Handoff Chains)
worktrees	parallel-worktrees, contract-fanout, stack-branches, stack-claude	Fan out to worktrees; coordinate slices against contracts; stack work-in-progress branches (Parallel Worktrees)
tmux	tmux-archive, tmux-organize	Snapshot every pane with links to its agent; rename and regroup windows from their contents (tmux)
memory	reflect, dreaming, session-analyzer	End-of-session retrospectives, nightly consolidation, transcript analysis (The Reflection Store)
codex	codex-subagents, codex-transcripts	Drive Codex through tmux; read what a Codex agent really did (Codex)
review	adversarial-review, mcp-agent-safety, fable-second-opinion	Reviews whose findings must survive refuters; canary tests for MCP servers; a second-opinion advisor

Beyond its own, Cole’s setup enables a curated set from Anthropic’s official marketplace (the TypeScript, Pyright and Swift language servers, Playwright, Context7, code-simplifier, commit-commands, feature-dev), Cloudflare’s skills marketplace, and skills linked from the public agent-skills collection (handoff, autoreview, session-viewer). Drover ships its own two skills, drover and drover-manager.

That is a real decision in Cole’s settings: one widely used plugin is off on every machine because its startup hook told every session to invoke a skill before any reply, which fought Cole’s own skills and output style, and its skills overlapped ones Cole already had.

How the skills are shared

Across machines. Skills live in source repositories, and the installed copies are symlinks into those checkouts, so editing an installed skill is editing its source and the two can never drift apart. A sync step fast-forwards each skill checkout to its deployment branch on every machine during dotsync, and refuses to touch one that is dirty, detached or ahead. Every machine ends up with the same skills. See Dotfiles.

Between Claude Code and Codex. The installer links every skill in ~/.claude/skills/ into ~/.codex/skills/, leaving Codex’s own bundled skills alone and pruning links whose skill was removed. Codex reads the same format, and its global AGENTS.md says how to read a skill written for Claude: the knowledge (conventions, checklists, commands) applies as written; Claude-only mechanics such as the Skill and Agent tools or slash commands get translated to what Codex has.

To the public. Cole writes and runs everything in a private repository first. A file reaches the public dx repo only by being named in an export allowlist, as a verbatim copy, a generalized adaptation, or a skip, and only after a scrub gate passes on the whole result. The gate runs secret scanners over the tree and its history, a denylist of shapes (email addresses, phone numbers, private and tailnet addresses, host names, home paths, account ids, key shapes) over every file, path and commit message, and fails closed: a missing scanner or an unreadable file is a failure, not a skip. It prints file:line and the rule name, never the matched text, so its own output cannot leak what it found.

Linked, not copied. Other people’s skills are linked from their repositories rather than copied in, and credited.

Writing a good skill

Patterns from Cole’s own skills:

• Lead the description with when to use it, in the user’s words (“Use when the user says ‘park my idle sessions’…”). Descriptions are cut off past about 1,500 characters in the listing.
• Put the most important instructions first. After compaction, an invoked skill’s body comes back capped, and the cut keeps the start.
• Write the traps down. Cole’s skills end with “Gotchas” or “Traps it handles (learned the hard way)”, each with the date or the symptom that taught it.
• Answer the excuses. The handoff skill has a “Rationalizations” table pairing each excuse an agent might make (“I’ll suggest it to the user instead”) with why it is wrong.
• Ship the CLI with tests. A skill that drives a script is only as good as the script; the CLIs in dx have hermetic test suites, and CI runs them on every push.
• One skill, one job. A skill that tries to cover three workflows never triggers at the right moment for any of them.