Claude Code

Set up pair with Claude Code, configure AGENTS.md, CLAUDE.md, the .claude/ directory, invoke skills, and customize distribution.

Prerequisites

Claude Code installed and authenticated
A pair-enabled project (pair-cli install completed, .pair/ directory exists), required for the CLI channel, optional for the marketplace channel
Node.js 18+

pair reaches your project through one mechanism: the CLI writes the knowledge base and the skill catalog into your repo. The Claude Code marketplace is the zero-setup entry point to it: it ships a single bootstrap skill that installs the CLI and runs it for you.

Step	Command	What it does
Marketplace (Claude Code native)	`/plugin marketplace add foomakers/pair` → `/plugin install pair@pair`	Installs one skill: `/pair-assistant`
Assistant	`/pair-assistant`	Sets pair up when it is missing, installs `pair-cli` (locally when your project has a `package.json`, otherwise via `npx`), creates the git repository if there is none, runs the install. Then stays useful: it turns a request into the right CLI command, and answers questions about your project from your own `.pair/llms.txt`
CLI (tool-agnostic)	`pair-cli install` / `pair-cli update`	Writes `.pair/` (knowledge base + adoption files), `.claude/skills/`, and `.claude/workflows/` + `.claude/agents/` (the batch engine, whose agents can run `git`/`gh`). Those last two install unconditionally, on every project (there is no install-time tool gate; they are simply inert files when the project is not driven by Claude Code) also what you run directly if you skip the marketplace, or if you use Cursor, Windsurf or Copilot

You are not choosing between two copies of the catalog: the marketplace never ships it. That is what makes the two safe to have installed at once, see below.

Marketplace Install

/plugin marketplace add foomakers/pair
/plugin install pair@pair
/pair-assistant

The plugin is optional and Claude Code only. What it installs, how to update and remove it, what /pair-assistant can do and how it writes are on Claude Code plugin & /pair-assistant.

You are not choosing between two copies of the catalog: the plugin ships one skill and the CLI never installs that one, so both can stay installed. Keep the plugin for the next project, or remove it with /plugin uninstall pair@pair.

Configure Agent File

CLI channel only. Everything from here to Use Skills (the project structure, AGENTS.md/CLAUDE.md generation, the .claude/ directory, the bridge pattern) describes a project set up with pair-cli install. On the marketplace channel none of it exists in your repository: the skills and the knowledge base live in the plugin cache.

Claude Code reads two files at the repository root plus the .claude/ directory:

Project Structure

your-project/
├── AGENTS.md                    ← universal bridge file (all AI tools read this)
├── CLAUDE.md                    ← Claude Code-specific (generated from AGENTS.md)
├── .claude/
│   ├── settings.local.json      ← permissions and allowed tools
│   └── skills/                  ← canonical skill directory
│       ├── pair-next/
│       ├── pair-process-implement/
│       ├── pair-capability-verify-quality/
│       └── ...                  ← 51 skills
├── .pair/
│   ├── knowledge/               ← upstream guidelines (don't edit)
│   └── adoption/                ← your project decisions
└── ...

AGENTS.md

The universal bridge file. pair generates it during pair-cli install. It contains:

Task selection algorithm (which how-to guide to follow)
Essential commands (pnpm install, pnpm test, pnpm lint)
Key references to adoption files and guidelines
Quick rules (testing, commits, adoption checks)

Claude Code reads AGENTS.md automatically when entering a repository. No manual configuration needed.

CLAUDE.md: Generated from AGENTS.md

CLAUDE.md is not written manually, pair generates it automatically from AGENTS.md using the transform pipeline defined in config.json. The agents registry controls this:

"agents": {
  "source": "AGENTS.md",
  "behavior": "mirror",
  "targets": [
    { "path": "AGENTS.md", "mode": "canonical" },
    { "path": "CLAUDE.md", "mode": "copy", "transform": { "prefix": "claude" } }
  ]
}

The transform: { "prefix": "claude" } applies marker-based rewrites: the KB source AGENTS.md can include or exclude sections for specific targets using markers:

<!-- +claude: Claude Code-specific section -->
### Claude Code Tips
Use `/pair-next` at session start. Skills are slash commands.
<!-- +claude -->
 
<!-- -claude: Exclude from CLAUDE.md -->
### Generic section
This content appears in AGENTS.md but not in CLAUDE.md.
<!-- -claude -->

After transformation, all markers are stripped from the output. This lets a single source file produce tool-specific variants without duplication.

The .claude/ Directory

The .claude/ directory is Claude Code's native configuration location:

.claude/skills/: the canonical copy of all pair skills. Other AI tool directories (.github/skills/, .cursor/skills/, etc.) are symlinks pointing here.
.claude/settings.local.json: Claude Code permissions (allowed Bash commands, MCP tools, additional directories).

The Bridge Pattern

All files point to .pair/: the single source of truth:

AGENTS.md    ──→ .pair/knowledge/     (guidelines, how-to guides)
CLAUDE.md    ──→ .pair/adoption/      (your decisions)
.claude/skills/ ──→ .pair/ (skills reference adoption + knowledge)

When you update adoption files or install new skills, Claude Code picks up the changes at the next session start.

Use Skills

Skills are invoked as slash commands in Claude Code:

/pair-next                    # what should I work on?
/pair-process-implement #42   # implement story #42
/pair-process-review          # review current PR

Common Skills

Skill	Purpose
`/pair-next`	Determine next action based on project state
`/pair-process-specify-prd`	Create or update Product Requirements Document
`/pair-process-plan-initiatives`	Plan strategic initiatives from PRD
`/pair-process-plan-epics`	Break initiatives into epics
`/pair-process-plan-stories`	Break epics into user stories
`/pair-process-refine-story`	Refine a story with acceptance criteria
`/pair-process-plan-tasks`	Break a story into implementation tasks
`/pair-process-implement`	Implement a story task by task
`/pair-process-review`	Structured code review

For the full catalog, see Skills Catalog.

Skill Discovery

Claude Code discovers skills in .claude/skills/. pair installs skills there during pair-cli install or pair-cli update. Each skill is a SKILL.md file that Claude Code reads when you invoke the corresponding slash command.

Skills are installed through the transform pipeline: the KB source uses a category structure (.skills/process/implement/) which gets flattened and prefixed:

KB source:    .skills/process/implement/SKILL.md
Flatten:      process/implement → process-implement
Prefix:       process-implement → pair-process-implement
Installed:    .claude/skills/pair-process-implement/SKILL.md

This happens automatically during pair-cli install and pair-cli update.

Workflow Tips

Start Every Session with `/pair-next`

This reads your adoption files and PM tool state, then recommends the most relevant action. It keeps sessions focused and prevents context loss between conversations.

Commit Strategy

pair supports two strategies configured in your way-of-working.md:

Commit per task: one commit per task, with checkpoints between tasks
Commit per story: continuous flow, single commit at story end

Both strategies produce a single PR per story. The choice affects how granular your Git history is during development.

Session Context

Claude Code maintains context within a session but starts fresh in new sessions. AGENTS.md and CLAUDE.md ensure it recovers project context automatically. For long-running work, the /pair-process-implement skill tracks progress in the PM tool so you can resume across sessions.

Verify It Works

Open Claude Code in your pair-enabled project and run:

/pair-next

Expected output: Claude Code reads your adoption files and suggests the next action (e.g., "Story #42 is refined and ready, run /pair-process-implement #42"). If it can't find .pair/, check that pair-cli install completed successfully.

Agent Integration concept
Claude Code plugin & /pair-assistant
Skills Catalog
CLI Reference
Configuration Reference: full config.json documentation
Skill Management: transform pipeline details