Plugins & Skills · crystl Docs

The eager-load surface

Every turn, your agent sends:

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.

Two management surfaces

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

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.

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:

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:

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.

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.

Related docs