Plugins & Skills

Updated November 17, 2026

Claude Code and Codex both load a fixed bundle of context into every API call: system prompt, tool definitions, walked-up agent files, and the frontmatter of every installed plugin and skill. None of it is optional per turn. It costs tokens whether you use it or not.

crystl lets you scope that bundle per gem. A Vercel project doesn’t need Shopify or Cloudflare loaded; a Swift project doesn’t need either. The plugin and skill management surfaces in crystl turn that one-size-fits-all global config into something tuned per project.

The eager-load surface

Every turn, your agent sends:

  • The agent’s system prompt (Claude Code’s or Codex’s)
  • All tool definitions: built-in tools and every connected MCP server
  • Walked-up CLAUDE.md / AGENTS.md files
  • Every installed plugin’s manifest and the frontmatter of skills bundled inside those plugins
  • User-level skill frontmatter: ~/.claude/skills/*/SKILL.md for Claude, ~/.agents/skills/*/SKILL.md for Codex

The frontmatter and manifests are how the model “knows” a skill exists so it can decide to invoke one. That discoverability is exactly why they’re eager-loaded, and exactly why they cost tokens on every turn even when nothing in the session needs them.

See context load tracking for how crystl measures the size of that bundle live.

Two management surfaces

crystl gives you two places to toggle plugins and skills. Both write to the same underlying config:

  • Context Load Panel (per-shard view): opens from the ~N turns left readout at the end of the shard status band. It shows the live token cost of the current shard’s plugins and skills and offers row-level disable actions.
  • New Gem / Gem Settings → agents (per-gem configuration): checkbox grids for installed Claude Code plugins and user-level Claude skills. Changes apply when you create or save the gem.

For Claude entries, both surfaces edit the same per-gem settings file. Codex plugin and skill switches are global, on settings, agents > codex, not in Gem Settings.

What crystl writes

Claude Code

Per-gem state is stored in <gem>/.claude/settings.json under two keys:

{
  "enabledPlugins": {
    "vercel@claude-plugins-official": false
  },
  "skillOverrides": {
    "my-personal-skill": "off"
  }
}

A false value tells Claude Code to skip loading that plugin or skill for sessions started in this directory. Re-enabling strips the entry entirely rather than writing true, so crystl-managed settings stay minimal and don’t drift from upstream defaults.

When a setting needs to apply globally (a user-level skill that should never load anywhere), crystl writes the same shape into ~/.claude/settings.json instead.

Codex

Codex doesn’t have per-project plugin scoping. crystl writes to the global config at ~/.codex/config.toml:

[plugins."vercel-plugin@plugins-cli"]
enabled = false

Flipping the entry back to enabled = true re-enables it everywhere. There’s no project-level override to layer on top.

Platform differences

Claude Code Codex
Per-gem scope yes (<gem>/.claude/settings.json) no (global only)
User skill location ~/.claude/skills/ ~/.agents/skills/
Mid-session apply yes (crystl injects /reload-plugins automatically) no (requires manual codex restart)
Re-enable strips entry from settings.json flips enabled = false to true

If you mix agents in one gem, expect Codex changes to leak across all your projects. This is a Codex limitation, not a crystl one.

Mid-session reloads

After you toggle plugins or skills for a Claude shard, crystl writes the settings file and then injects /reload-plugins into the active shard. Claude Code picks up the new config without restarting, and the next turn runs against the trimmed context.

Codex has no equivalent reload command. crystl leaves a hint in the shard reminding you to restart codex for the change to take effect.

Auto-detect on new gem creation

When you create a new gem in a directory that already has files, crystl scans for known stack markers and proposes a tailored plugin config before the gem is saved.

The current marker set:

Marker Suggestion
vercel.json, next.config.* Vercel
shopify.app.toml Shopify
wrangler.toml / wrangler.jsonc Cloudflare
supabase/config.toml Supabase
.sentryclirc / sentry.properties Sentry
Package.swift swift-lsp + code-review

Multiple matches union into a single suggestion: a Next.js project on Cloudflare Workers with Sentry wired up gets all three plugins proposed. The dialog gives you three buttons:

  • Accept: enable the suggested set and disable everything else
  • Customize: return to the New Gem panel without changing the current checkbox state, then make your own selection before saving
  • Skip: create the gem with whatever plugins are currently enabled globally

Skipping is a one-time choice. You can always open Gem Settings later to revisit.

The context load panel

The panel doubles as a live budget for the shard’s eager-load surface. Each plugin and skill appears with:

  • Token cost: the size of that entry’s manifest or frontmatter as Claude actually sees it
  • Source: global (~/.claude/), per-gem (<gem>/.claude/), or plugin-bundled
  • Disable actions: click the row for a menu to disable the entry for this gem or globally, or re-enable it

Disabling an entry from the panel is the fastest way to free up context without leaving the shard. crystl writes the change, fires /reload-plugins, and the indicator in the status bar updates on the next turn.

The gem settings panel

Opening Gem Settings from the gem menu (the ⋮ on a gem tab → settings) and choosing the agents tab shows ENABLE CLAUDE PLUGINS and ENABLE CLAUDE SKILLS sections when matching entries are installed. The New Gem panel exposes the same sections before creation.

The plugin list contains installed Claude Code plugins; the skill list contains user-level Claude skills. Unchecking writes the matching disable entry to <gem>/.claude/settings.json. The panel batches changes and writes once on save, so toggling a dozen entries doesn’t thrash the settings file.

MCP server enablement is a separate section on the same tab. Codex plugins and skills do not appear as per-gem checkboxes because Codex only offers global scope; use the link from the panel to open the Codex settings page.

Import a folder of skills

If you already have skills in a folder, crystl can copy them all into the folders your agents read. You pick the folder, check a preview, and click import.

Open settings, context, and choose the skills tab. The import skills button sits beside browse library on both sub-tabs. Both open the same panel. The sub-tab only decides which agent box starts ticked.

What you can pick

The picker says: choose a folder of skills, one skill folder, a .zip or a .skill. You pick one thing at a time.

  • A folder of skills. Every folder inside it that holds a SKILL.md file is a skill. crystl looks up to three levels down, so a plugin’s skills/<name>/SKILL.md layout works too.
  • One skill folder. A folder with a SKILL.md in it.
  • A .zip or a .skill. A skill export from Claude.ai is a zip, and it imports the same way.

Loose .md files in the folder you pick are imported as skills too, which covers a folder of Claude Code commands. Each file becomes its own skill folder. A file with no description gets one from its first paragraph, and its row tells you so. README.md, LICENSE.md and CHANGELOG.md are listed but start unticked.

The preview

The panel lists one row per skill it found, each with a tick box, the name and the description. Nothing is copied until you click the import button. Three settings sit above the list.

SAVE TO has two choices. this mac saves the skills for every gem on your Mac. The second choice names the open gem, like notes only. It saves the skills in that gem’s folder, so only that gem gets them. Anyone who gets a copy of that folder gets the skills too. The gem choice appears when a local gem is open.

FOR THESE AGENTS has three boxes. Tick at least one. On this mac, agents do not share one skills folder, so each box copies to the folder that agent reads. For one gem, every box saves to the same folder, <gem>/.agents/skills.

Box this mac one gem only
claude code ~/.claude/skills <gem>/.agents/skills, and Claude Code reads it through a link from <gem>/.claude/skills
antigravity ~/.gemini/config/skills <gem>/.agents/skills
codex, kimi and other agents ~/.agents/skills <gem>/.agents/skills

The panel shows the folders it will copy to under the boxes. On this mac, with more than one folder, each agent gets its own copy. An edit to one copy does not change the others. For one gem there is one copy, so an edit reaches every agent.

Claude Code reads only .claude/skills. When you tick claude code for a gem, crystl makes <gem>/.claude/skills a link to .agents/skills if nothing is there yet. It writes the link as a relative path, so a moved or copied gem keeps it. If the link is already there, crystl leaves it as it is.

crystl does not change the gem’s own .claude/skills in these cases. It still copies the skills into .agents/skills, and the panel warns that Claude Code will not see them:

  • The gem has its own .claude/skills folder. Claude Code reads that one. To let Claude Code see the imported skills, open the gem’s files drawer and click move existing skills… after the import.
  • .claude/skills is a link to somewhere else. Move the link to the Trash. This does not change the folder it pointed to. Then click link for Claude Code in the files drawer.
  • A file sits at .claude/skills. Rename the file or move it to the Trash, then click link for Claude Code.
  • The gem’s .claude folder is a link to a folder outside the gem. A link from .claude/skills would land in that folder, and every gem and Claude Code session that reads it would get these skills. So crystl makes no link there. Move the .claude link to the Trash, copy what the gem needs into a new .claude folder, then click link for Claude Code.

In Finder, press Command-Shift-period to show folders whose names start with a dot.

If the gem’s .agents/skills is itself a link to a folder outside the gem, crystl saves the skills in the folder it leads to. The panel names that folder. Every gem and agent that reads it gets the skills.

WHEN A NAME IS TAKEN sets what happens when a skill with the same name is already installed. It sets every such row at once, and each row has its own menu if you want a different answer for one skill.

  • skip leaves the installed skill alone. This is the default.
  • replace moves the installed skill to the Trash and puts the new one in its place.
  • keep both saves the new skill beside the old one as <name>-2.

Each row carries a badge:

Badge Meaning
NEW No skill with this name is installed
ALREADY INSTALLED The same skill is installed already, byte for byte. The row starts unticked
NAME TAKEN A different skill holds the name. A note under the row says which one and where. For Claude Code, a command with the same name counts too. In a gem, a skill in the gem’s own .claude/skills folder counts too
NO DESCRIPTION The skill has no description, so an agent may not know when to use it. You can add one after the import
TOO LARGE The skill is over the size limit and is not imported

Skills that crystl maintains itself, the ones whose names start with crystl-, cannot be replaced. Those rows offer skip and keep both.

crystl never changes a gem’s own Claude Code files. So when a name is held only by a skill in the gem’s own .claude/skills folder, or by a command file in .claude/commands, the row offers skip and keep both, and a note says why there is no replace. A skill with the same name in .agents/skills can still be replaced. The Claude Code file stays where it is.

What the import does to your files

  • It copies. Your original files stay the same. Edits you make in crystl afterwards change the copy.
  • The whole skill folder is copied, extra files included. A script stays executable.
  • A replaced skill goes to the Trash, so you can get it back. crystl checks the new copy first. If the copy fails, the installed skill stays where it was.
  • The copy’s name line is set to the folder name. The name of a skill is its folder name: lowercase, hyphens for spaces, up to 64 characters. If the SKILL.md names the skill something else, crystl writes the folder name into the copy and the row tells you. This keeps the name you see, the name an agent loads and the per-gem switch in agreement.

After the import

The panel stays open and shows a count, like added 58 · replaced 1 · skipped 3. Each row now shows what happened to it: ADDED, REPLACED, RENAMED, SKIPPED or FAILED. A skipped or failed row says why. If some skills failed, fix what the row names and import again. crystl skips the skills it already added.

Each imported row has an edit action that opens the installed SKILL.md in the skill editor. The skills tab behind the panel already lists the new skills. Skills saved for Antigravity on your Mac appear on the other agents sub-tab under ANTIGRAVITY.

Agents in new shards can use the skills straight away. Restart an agent that is already running. If Claude Code is running in a gem that had no .claude/skills before the import, type /reload-skills or restart it, because Claude Code only notices a new top-level skills folder at start.

For a gem, Claude Code cannot see the skills when crystl left the gem’s .claude/skills alone (see the cases above). The panel and the done line say so. Follow the step they give, then restart Claude Code in that gem. The import itself still worked: every skill was copied to .agents/skills, and Codex, Antigravity and other agents read it.

Turn a skill off for one gem

Skills saved to this mac are on in every gem, and each one’s description is sent on every turn. For Claude Code you can turn a skill off per gem: open gem settings, choose agents, and untick it under ENABLE CLAUDE SKILLS. See the gem settings panel.

Antigravity, Codex and other agents have no per-gem switch for skills. To keep a skill to one gem for those agents, save it to that gem under SAVE TO.

Limits

  • Remote gems are not supported yet. When the open gem is on another computer, the import saves to your Mac. The panel gives you an scp command for each agent you ticked, with a copy button, so you can copy the skills to the host yourself.
  • A skill over 50 MB or 1,000 files is not imported. To use it, copy its folder into the skills folder yourself.
  • Links that point outside a skill are skipped. The row names each one. If the skill needs that file, copy it into the skill folder and import again. A link to a file inside the same skill is copied as a plain file. Links inside a zip are never copied: unzip it in Finder and import the folder.
  • A file crystl cannot read as text is skipped and named. Save it as plain text (UTF-8), then import again.

The same import runs from the terminal: see crystl skills import.

Working with plugin manifests

crystl doesn’t install plugins itself. It reads whatever claude plugins or the Codex equivalent have already installed. Adding a new plugin to a marketplace registry (or installing one with claude plugins install) makes it appear in crystl’s grid on the next gem open.

For plugins bundled with skills, the per-skill toggles are independent: you can keep a plugin enabled (so its slash commands work) while disabling a few of its bundled skills you never use.

Best practices

Default to disabled, opt back in. A clean global config with most plugins off is usually cheaper than the inverse. Use auto-detect on new gems to switch the right ones back on per project.

Audit the context-load panel weekly. Plugin authors update frontmatter all the time; an entry that was cheap last month may have ballooned. The panel shows the current cost, not the cost at install.

Don’t enable everything “just in case.” Every enabled plugin and skill subtracts from your usable window for actual work. The model can be told about a skill mid-session via documentation; the eager-load surface is for skills it should always know exist.

Codex needs care. Because Codex toggles are global, the safest pattern is to keep its global plugin set lean and put project-specific instructions in AGENTS.md instead.