Skill Management

pair skills are SKILL.md files that live in the Knowledge Base and get distributed to AI tool directories. This page explains the three mechanisms that make this work: resolution, transformation, and renaming.

Skill Resolution

The Problem

Skills are authored in a category-based directory structure (capability/verify-quality/SKILL.md) but AI tools expect them in a flat target directory (.claude/skills/). The CLI needs to locate the right source files and map them to the right targets.

How It Works

Resolution is registry-based, not runtime file scanning. The config.json declares the source directory, target directories, and transform rules:

{
  "skills": {
    "source": ".skills",
    "targets": [
      { "path": ".claude/skills/", "mode": "canonical" },
      { "path": ".github/skills/", "mode": "symlink" }
    ]
  }
}

Source Types

Skills come from three sources:

Resolution Order

1. CLI reads config.json to find the skills registry entry
2. Scans the source directory (.skills/) for all SKILL.md files
3. Applies naming transforms (flatten + prefix)
4. Copies to canonical target (.claude/skills/)
5. Creates symlinks for secondary targets (.github/skills/, .cursor/skills/, etc.)

Transformation Pipeline

The Problem

A raw SKILL.md file contains relative links, short skill names, and category-based paths. After installation, these need to work in a flat directory structure where all skills are siblings.

Pipeline Stages

The pipeline runs during pair install and pair update:

Stage 1: Copy with naming transforms

Source:  .skills/capability/verify-quality/SKILL.md
Target:  .claude/skills/pair-capability-verify-quality/SKILL.md

Stage 2: Frontmatter sync

# Before (source)
name: verify-quality
 
# After (installed)
name: pair-capability-verify-quality

Stage 3: Link rewriting

<!-- Before: relative link in category structure -->
See [record-decision](../../capability/record-decision/SKILL.md)
 
<!-- After: sibling link in flat structure -->
See [record-decision](../pair-capability-record-decision/SKILL.md)

Stage 4: Skill reference rewriting

<!-- Before -->
Composes /verify-quality and /record-decision.
 
<!-- After -->
Composes /pair-capability-verify-quality and /pair-capability-record-decision.

Stage 5: Multi-target distribution

.claude/skills/pair-capability-verify-quality/  (canonical — physical copy)
.github/skills/pair-capability-verify-quality/  (symlink → .claude/skills/...)
.cursor/skills/pair-capability-verify-quality/  (symlink → .claude/skills/...)

Stage 6: Cross-registry propagation

After all registries are installed, skill references in non-skills files (like AGENTS.md) are also rewritten:

<!-- AGENTS.md before -->
Run /next to get started.
 
<!-- AGENTS.md after -->
Run /pair-next to get started.

Concrete Example

Here's a full before/after for the implement skill:

Before (source):

Path: .skills/process/implement/SKILL.md
Frontmatter: name: implement
Body: Composes /verify-quality and /record-decision.
Link: See [verify-quality](../../capability/verify-quality/SKILL.md)

After (installed):

Path: .claude/skills/pair-process-implement/SKILL.md
Frontmatter: name: pair-process-implement
Body: Composes /pair-capability-verify-quality and /pair-capability-record-decision.
Link: See [verify-quality](../pair-capability-verify-quality/SKILL.md)

Renaming Conventions

The Problem

AI tools invoke skills by directory name (e.g., /implement). Without namespacing, skill names could collide with other tools' commands. Prefixing with pair- and the category creates unique, discoverable names.

Naming Rules

The transform is deterministic: {prefix}-{category}-{skill-name}

With the default config (prefix: "pair", flatten: true):

Three Namespace Prefixes

Transform Functions

The naming transform applies two functions in order:

1. Flatten: Replace / with -

   • capability/verify-quality → capability-verify-quality

2. Prefix: Prepend the prefix with - separator

   • capability-verify-quality → pair-capability-verify-quality

// Flatten: replaces '/' with '-'
function flattenPath(dirName: string): string {
  return dirName.replace(/\//g, '-')
}
 
// Prefix: prepends prefix with '-' separator
function prefixPath(dirName: string, prefix: string): string {
  return `${prefix}-${dirName}`
}

Reference Rewriting Rules

Skill references (slash commands in markdown) are rewritten using boundary-aware matching:

• Only references with a leading / are rewritten (e.g., /next but not next)
• Longest matches are processed first to avoid partial replacements
• Boundaries include: start/end of line, whitespace, backticks, quotes, parentheses, pipes

Examples:

Windows Compatibility

On Windows, symlink targets fall back to copy mode because symlinks are not reliably supported. This means secondary targets (.github/skills/, .cursor/skills/) get independent copies instead of symlinks.

Related

• Skills Catalog — All 31 pair skills
• Configuration Reference — config.json registry settings
• KB Structure Reference — Directory layout