Skills

A skill is a folder with a SKILL.md that teaches Claude or Codex how to do something: your review method, a release checklist, how to use a tool. Claude and Codex each look for skills in their own places, and neither shows you the other's. The Skills tab lists every skill both apps can load, in one calm list, and shows quietly which app can use which. A skill in only one app is fine: nothing nags you about it. One switch keeps your skills the same in both apps, and the only things the tab ever points out are a skill you changed in both apps and a skill that's actually broken.

Where they come from#

A folder both apps load (for example ~/.agents/skills/deploy linking to ~/.claude/skills/deploy) is one skill with two copies in the same place: nothing to fix.

The list updates by itself when a skills folder changes, and again whenever you open the tab. For plugins, Pairbar reads only which plugins are installed and on: from settings.json only enabledPlugins, from Codex's config.toml only the names of its [plugins."…"] tables and their enabled. Nothing else in those files (your MCP servers' keys and environment) is kept, shown or logged.

The Skills tab#

Group names wrap in full. Below 280 points the skill count appears beneath the name; click the header to fold or unfold the group.

At the top: the search, the Filter menu and ⋯. Under them, Keep skills the same in Claude and Codex, with its switch (below 280 pt the switch sits beneath the explanation); then the list, grouped by where the skills come from:

1. This project: the skills of the repo the chat you're in works in (with no chat in front, Projects: every repo's).
2. Personal: yours, in ~/.claude/skills, ~/.agents/skills and ~/.codex/skills.
3. Other projects: other repos' skills (folded at first).
4. Plugins: plugins', your claude.ai account's and the apps' own (folded at first, with how many).

Click a section's title to fold or unfold it; Pairbar remembers.

A skill in the list#

Each row is the skill's name, a short description and two small app marks, Claude's and Codex's. Below 360 pt, the full name wraps, the description previews up to two lines, and the app marks sit below the text. Wider rows keep the description to one line. Hover the name or description to read its full text, or open the row for its details. The app marks are separate from the button that opens the details: full when that app can use it, faint when it can't. Hover a mark for what it means: "In Codex only · Make available in Claude", "In Claude only · it runs commands when it loads, which only Claude can do", "In Claude and Codex". A faint mark you can do something about is a button: click it to make the skill available in that app.

Click a row and its details open in place. Copy and Make available buttons wrap their full labels when space is limited:

• the whole description, and where its SKILL.md is (Whole path shows all of a long one);
• which apps can use it;
• Use in chat (when the chat in front is in an app that can use it): types /name or $name into that chat's message box, nothing sent. Otherwise Copy /name (or $name).
• Open file: its SKILL.md in your default editor.
• Make available in Claude (or Codex), when only the other app has it: a link from that app's skills folder, or a translated copy when Codex needs one (see What fixes write). It's done at once; the notice has Undo. A project's skill gets a relative link in its repo.
• Remove…: moves your copies of it (and the links to it) to the Trash, after you look at the plan; Undo puts them back. Not for a plugin's skill.
• All details: the skill's page (below).

Right-click a row for Use in chat, Copy invocation, Use in a workflow and Reveal in Finder. Drag a row onto Claude's or Codex's message box to drop the skill there.

Suggested here#

When Claude or Codex shows a chat, the top of the tab lists the skills that fit it: the project's own skills first, then the ones its workflows and agents use, then those whose name or description shares a word with the chat's title or branch (the same ranking as the chat's context). Each row says why ("Acme-Backend's own skill", "Matches review") and which app can use it, and follows you as you switch chats. It's hidden while you search or filter.

• Use in chat types the skill into that chat's message box, the way the app calls it: /review-method in Claude, $review-method in Codex. The cursor is left after it and nothing is sent, so you can add what you want it to do. Pairbar types it as key presses sent to Claude or Codex only (it needs Accessibility, which the sidebar already uses); without that permission it copies the text instead and says to paste it with ⌘V.
• A skill the chat's app can't use yet shows Make available… instead: it opens the plan for Make available to Codex (or Claude), or for a plugin's skill a copy (see below). A skill that can't work there says why ("Claude only: runs commands when it loads").
• Drag any skill (here or in the list) onto Claude's or Codex's message box: it drops the same text. It carries the syntax of the focused chat's app when that app can use the skill, else of the app that can.
• Use in chat is also on a skill's page, in a row's right-click menu, and in the chat's context card.

Keep skills the same in Claude and Codex#

Off by default. Turn it on with the switch at the top of the tab (or Settings → Agents & workflows → Keep skills the same in Claude and Codex) and Pairbar mirrors your personal skills between the apps in the background, each time a skills folder changes:

• a skill only one app has gets a link in the other app's folder, or a translated copy when it uses Claude-only syntax (the same choice as Make available);
• a translated copy whose original you changed is written again (the old one backed up first);
• copies of one skill that differ are brought to one version, each other copy backed up first. Which version: the one that changed since the copies last agreed (Pairbar remembers each skill's agreed version, in ~/.pairbar/skills-sync.json); without that, the newest when that's clear.

The first time it runs, Mirrored available skills lists what it did, with Undo; after that it's quiet. It never:

• writes over a change you made in both apps. When more than one copy changed since they last agreed (or "newest" is only a guess), or you edited a translated copy while its original changed, nothing is written: one small line says 1 skill changed in both apps · Review. Review opens a page with each version (which app, where, when it changed). View version shows that copy’s SKILL.md in a scrollable block; Hide version closes it. Paths and actions wrap in narrow sidebars. Then: Keep this one gives the others its files (backed up first; the result has Undo), Leave them different keeps both until one changes again. For a translated copy you edited while its original changed, Update from original regenerates the translated copy, backs up your edit and leaves the original unchanged; Undo restores the edit. Keep my edit preserves both files until either changes again. This choice does not copy your edited translation back into the original.
• writes inside your repos (that would leave new files in a repository): make a project's skill available from its row.
• puts back a link or copy you removed yourself, changes a plugin's, claude.ai's or the apps' own skills, or touches a copy another tool (like Paseo) manages.
• fixes a name clash or removes a broken link: those are problems.

A Claude-only skill (it runs commands when it loads, forks a context or has hooks) stays in Claude. Turn the switch off and nothing is written any more, and nothing asks you anything.

If you had Keep skills in sync automatically on (it offered new skills on a card), it's now this switch, on: the first mirror shows what it did, with Undo.

Problems#

A skill that's actually broken gets one line at the bottom of the list, 2 skills have problems · Review, and nothing else does. Review opens a page with each one, what's wrong and what to do:

Fix the safe ones does every low-risk fix on the page in one plan you look over first.

Sync all skills#

⋯ → Sync all skills… opens one plan that makes every skill of yours available to both Claude and Codex at once, to look over before anything happens, in this order:

1. Duplicates first. Codex's name clashes keep one copy (the managed one, else yours, else the newest) and the others go to the Trash; copies that drifted apart are brought to one version (the pinned, the managed, else the newest; the others backed up first). Where "newest" is a guess the step is left unticked, with the reason.
2. Each skill one app can't see, in the same scope: a link when it uses only what both apps understand, a translated copy (Claude's variables filled in) when it doesn't. A personal skill goes to your folder; a project's skill to the same repo (a relative link you can commit). A broken link where it goes moves to the Trash first, in the same step.
3. Copies Pairbar made that fell behind their original are written again (backed up first).

Only offered, unticked:

• Plugin skills (and claude.ai's, and the apps' own) are never changed. A copy for the other app is offered; it's yours, marked "Generated by Pairbar", and doesn't follow the plugin's updates.
• Broken links elsewhere in the skills folders (a drive that isn't connected looks the same).
• A skill you removed from an app yourself (see below).

Listed as Can't be synced, with why: a Claude-only skill (it runs commands when it loads, forks a context, or has hooks), two different skills that share a name in Claude and Codex (their descriptions differ: rename one), a folder already in the way, or a personal skill where the other app has a project skill of that name (Codex would list both, so $name wouldn't resolve).

Nothing is written until you Approve, and the result card has Undo for all of it. Each skill's step happens all together or not at all: if one can't be done (a folder Pairbar can't write, say), it's left as it was, the others go ahead, and the card lists what wasn't done and why; Undo still puts back everything that was. If a skill changes while the plan is open, Approve does nothing yet: the plan is made again from what's there now and says so; look it over and approve again. Run it again and there's nothing ticked: "Your skills are in sync".

A big library (hundreds of skills) is one plan too, folded by kind ("Link for Codex (220)"), with Approve always in sight.

Changes you make later#

Pairbar remembers what it made (~/.pairbar/skills-manifest.json) and never redoes something you changed. With Keep skills the same on, an edited copy whose original changed is a change in both apps and the others are handled by themselves; otherwise the skill's page has a card:

A card you dismiss comes back only if what it's about changes again. What you choose is kept in ~/.pairbar/skills-sync.json (readable only by you).

Finding a skill#

The search field says Find a skill or /command. It matches names, descriptions and commands.

• Search as you type, by name, description, how you call it (/review-method, $paseo), where it's linked from or who manages it. Every word you type must match; the matches are highlighted. Folder paths don't count (every skill's path says "skills"). While you search, folded sections show their matches too.
• Filter (one menu): Show All, This project, Personal or Plugins; App Both apps, Claude or Codex (the skills that app can use where you are); Sort by Name, Recently changed or Most used (in your chats in the last 30 days, then by your workflows and agents). The menu's chip says what's on ("Personal · Codex").
• Pairbar remembers the filter, the order and the folded sections (not the search). A filter you'd set with the old chips comes back as the menu's nearest choice.
• When nothing matches, Show every skill brings everything back.

The plan: approve or decline#

The button doesn't change anything yet. It opens Here's what Pairbar will do (the same sheet as a task's plan), in a focused review view with scrollable steps:

• every file operation, in plain words: "Link ~/.agents/skills/review-method → ~/.claude/skills/review-method", "Back up ~/.claude/skills/paseo (1 file) to ~/.pairbar/backups/skills/paseo-…", "Replace it with the copy from ~/.agents/skills/paseo (version d309031a, 2 days ago)", "Move ~/.codex/skills/paseo to the Trash";
• what each app sees before and after ("Codex: can't see review-method → $review-method, linked to ~/.claude/skills/review-method");
• why, and for a risky fix, what makes it risky;
• a tag on each fix: Changes files, or Review for a riskier one;
• Approve or Decline, always at the bottom of the sheet, however long the plan. In a plan of several fixes the button counts the ticked ones (Approve 7 changes), and the line above it says what they do: "7 of 9 selected · moves 6 folders to the Trash · undo available". Select all / Select none is next to them. Decline changes nothing.
• A long plan scrolls between the title and the buttons (a fade and a line show there's more), and ↓ 5 more jumps to the end.
• Fixes of the same kind fold into one line with one checkbox: "Duplicate skills listed twice in Codex (6)", "paseo, paseo-advisor, paseo-committee and 3 more", "Same fix for each: move the extra copy in ~/.agents/skills to the Trash". Its checkbox ticks or unticks them all (a dash when only some are ticked); click the line to see each one, with its own checkbox and exact operations. Folding never changes what a fix does.
• Keys: when the sheet opens it has the focus, so Return approves and Esc declines; ⌘↩ approves from anywhere in the window.

While reviewing a plan, its steps use the page’s height. The library search and filters return after Approve or Decline; the approval buttons stay below the scrolling steps. On narrow sidebars, the summary and selection action use separate rows, and the approval buttons wrap without shortening their labels. Unticked operations keep their text readable; their checkboxes show what will run.

After Approve a card says what was done, with Undo: it removes the links and copies Pairbar made (unless you've edited them since), puts replaced and updated files back from their backup, and brings trashed copies (and broken links) back from the Trash. If only some fixes succeed, the heading says partly done: completed operations have a green checkmark, and failed operations have a red cross with the reason. Undo remains available for what was completed. Each fix happens all together or not at all: if one fails, what it did is undone, the other fixes go ahead, and the card says which one wasn't done and why. In a plan that both removes a duplicate and makes the skill available to the other app, the link always goes to the copy that stays.

Fix the safe ones (on the problems page) builds one plan of every safe fix there (removing duplicates Pairbar made or exact copies nobody manages), each with a checkbox: untick what you don't want, then approve. Risky fixes are never in it: use their own button.

A skill's page#

• Its name, how you call it in each app (/review-method, $review-method), description and when to use it, and tags: Works in both apps, Needs small changes for Codex or Claude only, its allowed tools, its model.
• Cards for what can be done about its copies (copies that differ, a name clash, a copy Pairbar made that's behind or that you edited), and problems with the file: no frontmatter, a name that isn't lowercase with hyphens, a description over 1,024 characters (Codex cuts it)…
• Who can use it: for Claude and for Codex, whether it's loaded, everywhere or only in some projects, and why not ("Its plugin is turned off", "Listed 2 times, so $paseo won't resolve"). A Codex name clash shows Needs a fix, rather than a green Yes. In a narrow sidebar, status badges move below their descriptions and fix actions wrap so their labels remain readable. Use in a workflow is shortened to Workflow below 280 points; its tooltip still explains the action. Copy paths and version badges use the full card width, with the copy menu below on narrow sidebars.
• Where it's installed: every copy, with its app, source, folder, the start of its hash and tags (differs, linked, managed by …, off). Each copy's ⋯: Make available to …, Replace with the copy in …, Move this copy to the Trash… (each opens its plan to approve), Undo: remove what Pairbar made, Reveal in Finder, Copy path. The menu opens beside its button and can extend beyond the sidebar so its action names remain readable.
• Used by: how often your chats used it in the last 30 days, per app, or that they didn't (a skill nobody uses still costs room in every chat's skill list: a candidate to turn off); then the workflow steps and agents that use it (a pin shows pinned). Click one to open it.

How use is counted#

When you open the Skills tab (at most every 30 minutes), Pairbar reads the transcripts that changed in the last 30 days for skills being used: in Claude, a Skill tool call or a skill's slash command (/review-method); in Codex, a $name in a message you wrote. Only each skill's name and when are kept, in skill-usage.json in Pairbar's caches folder (readable only by you), per transcript file, so a file is read again only when it changed. A name counts for the skill in your library that has it (pairbar:advisor and advisor both count for Pairbar's advisor).

• Files in its folder, and its SKILL.md, rendered. If the preview cannot read the file, it shows the reason and Try again instead of continuing to load. Files over 256 KB must be shortened first; for other reading errors, check the location and permissions. Not checked means compatibility could not be checked from that file. An empty body says No instructions in SKILL.md yet. A preview fades only when its rendered text is taller than the preview; Show all reveals the rest, including long paragraphs that wrap on narrow sidebars. Short text stays fully visible. After fixing the file, Try again rereads it; file changes also refresh the preview.
• At the bottom: its full sha256, size, and about how many tokens it costs in every chat's skill list.
• Use in chat (when Claude or Codex shows a chat) types it into that chat's message box. Use in a workflow starts a new workflow whose first step uses it. ⋯ (Skill actions): Copy invocation, Open SKILL.md in…, Reveal in Finder. The menu shows the full invocation, and its app submenu can extend beyond a narrow sidebar. If no supported app is installed, Open SKILL.md in is unavailable.

What fixes write#

Only what the plan lists: links and generated copies (of your skills, or copies of a plugin's you ticked) in ~/.agents/skills or ~/.claude/skills (a project's skill: in its repo's .agents/skills or .claude/skills, as a relative link you can commit), backups in ~/.pairbar/backups/skills/<name>-<date>/ (readable only by you), and copies or broken links moved to the Trash. Pairbar never writes over something that's there, never changes a plugin's, claude.ai's or Codex's own skills, and never edits a copy another tool manages. What it made is recorded in ~/.pairbar/skills-manifest.json (readable only by you), so Undo removes only that.

Using skills#

• Workflow steps: the Skill chip on every step. See Workflows.
• New chats: the composer's Skill chip. The first message asks for the skill by name when the app can load it in that folder, or includes the skill's text when it can't. See New chats.
• Agents: an agent can list skills it always uses. See Agents.
• The workflow planner is told your skills (and which app loads each in the folder) and may give a step one or two when they clearly fit. It can only pick skills that exist; anything else is dropped.

Pairbar's own skills#

The Skill Library never installs anything into Claude or Codex by itself. Pairbar's own tools for agents come with the Pairbar plugin, which you install with one click: see Pairbar tools for Claude and Codex.