Packages and skills

A package is a versioned bundle of agent items (skills, rules, agents, commands, contexts, instructions) that teaches every coding agent on your project the same conventions. The Packages page is where you install packages, choose which of their items are active, and write them out for each agent your project uses.

Open it from the rail, or press g p (or ⇧ P). The page reads the project's files, so it is in the desktop app and the local workspace, not on the web workspace.

What you see

The page is a stack of cards, with an index on the left in three groups:

• explore: the Skills explorer, a catalogue of skills from skills.sh.
• managed: one card per installed package.
• local: Local items, the items your project keeps itself.

Each card states its value while closed, so you can see what is in the project without opening anything: "3 of 10 active · skills 2/4", "4 skills · 1 agent", or "skills.sh · ranked by Popular". Click a card, or move with J / K and open it with →, to see its contents in place.

The bar holds a filter (/), Sync (s) and Install package (a). When a package needs your attention, a button says how many (h goes to the first).

Screenshot to come/assets/docs/packages-cards.webp

The page is a view over the CLI. Each action runs the real command, and the dialogs show it before you run it.

If the folder is not an Invariant project yet, the page says so and gives the command to run in a terminal (invariant init claude): initializing picks which agents to sync to.

Install a package

1. Click Install package (a).
2. Pick the source:
   • GitHub ([): a repository as owner/repo, with an optional Ref (a branch, tag or commit).
   • Skills.sh (]): search for a skill, or paste owner/repo/skill. Browse all skills opens the Skills explorer.
3. Choose whether to Activate all items now (or Activate now for a skill) and whether to Run sync after.
4. Check the Installs as name and the Command preview, then click Install.

The package is downloaded into the project's cache under .invariant/ and appears as a card.

Choose which items are active

Installing a package caches all its items. Only active items are written out for your agents; inactive ones stay in the cache, ready to switch on.

1. Open the package's card. Its items are grouped by type, each with a tick box. All skills (or All rules, and so on) ticks a whole type; + and − add or remove everything.
2. Tick and untick what you want. Nothing runs yet: your changes are staged, and the card is marked unapplied.
3. The bar at the bottom of the card says what will change ("2 to add · 1 to remove") and shows the commands it will run.
4. Choose whether to Run sync after, then click Apply (⌘ S), or Discard (⇧ D).

If you reload or leave the page with changes not applied, the browser asks first.

Other actions on a package

• Open the source (o): the package's repository or skills.sh page.
• Uninstall (⌘ ⌫): removes the package, its cache and every item it added. A dialog shows the command and asks first.
• Install it (i): shown when a package is declared in invariant.json but not installed in this checkout, for example after a teammate added it. It fetches the package from its source.

Find skills in the Skills explorer

The Skills explorer lists skills from skills.sh, twenty at a time.

1. Open the Skills explorer card.
2. Switch between Popular and Trending with [ and ], or type in the search.
3. Select a skill to open its preview: its description, the name it Installs as, and its SKILL.md. Open on skills.sh (o) and Open on GitHub (⇧ O) open its pages.
4. Choose Activate now if you want it on at once, then click Install skill (⌘ Enter).

The list the explorer opens on is an interface preference: Settings → Interface → Skills catalogue opens on.

Screenshot to come/assets/docs/packages-skill-preview.webp

Local items

Local items lists the items your project keeps itself: files in the canonical store (.agents/ by default) that no package installed. Put a skill folder in .agents/skills and it appears here.

The card is read-only. These are your files: edit or delete them where they live. Invariant never deletes a local item. An item named like a package item but different from it is flagged, in case it is an edited copy.

Targets: which files get written

Each item is stored once, in the canonical store (.agents/). A target is an agent harness the project syncs to; for each target that is on, sync writes the items in the layout that harness reads.

Target	Context file	Items
Claude Code (claude)	CLAUDE.md	.claude/agents/, .claude/skills/, .claude/commands/, .claude/rules/, as links into .agents/
OpenAI Codex (codex)	AGENTS.md	Skills read from .agents/skills/; agents, commands and rules embedded in AGENTS.md
Cursor (cursor)	.cursor/rules/invariant-context.mdc	Skills read from .agents/skills/; agents, commands and rules as .cursor/rules/*.mdc
GitHub Copilot (copilot)	.github/copilot-instructions.md	Skills read from .agents/skills/; agents, commands and rules as .github/instructions/*.instructions.md
Aider (aider)	CONVENTIONS.md	Every item embedded in CONVENTIONS.md

Every context file starts with # Project Instructions: first the session protocol every agent follows, then the active instructions and contexts of your packages. Codex, Cursor and Copilot read .agents/skills/ themselves, so skills are not copied for them.

You choose the targets in the project's Settings → Agent targets. Turning a target on writes its files at the next sync; turning one off leaves its files alone, since they may have been edited by hand. See Settings and themes.

Claude's skills folder

Claude Code reads skills from .claude/skills. While that folder holds one link per skill, the Packages page offers, once, to make it a single link to .agents/skills, so Claude sees every skill there, local ones included:

• Link folder (l): one link for the whole folder. Entries Invariant did not write are kept, untouched, in .claude/skills.old/.
• Keep per-item links (⇧ L): one link per skill, as before.

Your answer is recorded in invariant.json, so the offer does not come back.

Sync

Sync writes the active items into every target and rewrites the agents' context files.

1. Click Sync (s).
2. Pick a Target, or leave Every configured target.
3. Check Replace hand-edited files only if you want to overwrite target files edited by hand. A confirmation says those edits are lost.
4. Click Check only (c) to report drift without writing anything, or Sync to write.

The result says "Everything is in sync", "Out of sync", "Synced" or "Sync failed", with the command's output. Check only is the same check you can run in CI.

Shortcuts

Keys	Action
g p	Go to packages
a	Install package
s	Sync
/	Filter packages
⌘ S	Apply staged changes
⇧ D	Discard staged changes
J / K · ← / →	Move between cards / open or close one

From the terminal

The same steps from a shell: invariant install github:owner/repo, invariant add and invariant remove to switch items on and off, invariant sync (with --check in CI), invariant target to change targets, and invariant uninstall. See Packages from the terminal.