Agent Skills in Knowledge Base

## Epic Information

**Epic ID:** EP-006
**Initiative:** [Dynamic Knowledge Base Management #64](https://github.com/foomakers/pair/issues/64)
**Epic Owner:** Product Engineer
**Status:** Done (8/8 stories completed — P0 Circle 1: 4/4, Circle 2: 4/4)
**Priority:** P0
**Epic Points:** 30-40 points (estimated)
**Target Release:** KB Skills Release

## Epic Statement

**As a** developer using AI-assisted development tools
**I need** the pair Knowledge Base to provide executable Agent Skills (agentskills.io standard) alongside the existing documentation
**So that** AI assistants can invoke structured, repeatable workflows instead of interpreting free-form markdown, improving consistency and reducing manual process overhead

### Epic Context

The pair KB currently provides excellent documentation (how-to, guidelines, adoption) but relies on AI assistants interpreting free-form markdown for every interaction. By introducing Agent Skills, we transform passive documentation into executable units that AI assistants invoke directly. This epic establishes the skills infrastructure, migrates operational content from how-to and guidelines into skills, and supports 5 AI tools (Claude Code, GitHub Copilot, Cursor, OpenAI Codex, Windsurf) through a registry-based installation system.

Design specification: `docs/design/skills-in-knowledge-base.md`

## Business Value &amp; Objectives

### Primary Business Goals
1. **Goal 1:** Transform KB from passive documentation to executable skills, reducing AI interpretation variability
2. **Goal 2:** Support the agentskills.io open standard across 5 major AI tools with a single source of truth
3. **Goal 3:** Enable incremental adoption — skills coexist with existing how-to documents, no breaking changes

### Success Metrics (KPIs)
- **Skill Invocation Success Rate:** Target ≥ 90% of skill invocations complete without manual fallback
  - **Measurement method:** Manual testing with Claude Code and Copilot
  - **Current baseline:** 0% (no skills exist)

- **How-to Size Reduction:** Target ~60% reduction in how-to file sizes (operational content migrated to skills)
  - **Measurement method:** Line count comparison before/after
  - **Current baseline:** 11 how-to files, ~3000+ total lines

- **Multi-tool Coverage:** Target 5 AI tools with working skill installation
  - **Measurement method:** Successful `pair install` with skill targets
  - **Current baseline:** 0 tools with skills support

## Problem Statement &amp; Market Opportunity

### Current State
AI assistants read how-to files as free-form markdown and must interpret instructions each time. This leads to inconsistent execution, missed steps, and no structured argument passing or tool restrictions. Guidelines contain decision matrices embedded in educational content, making operational workflows hard to extract programmatically.

### Target State
30 Agent Skills (SKILL.md format) organized in `dataset/.skills/` with registry-based installation to 5 AI tools. How-to files become thin orchestrators (~30-40% of current size) that compose skills. Guidelines retain educational content while operational workflows live in capability skills. The adoption binding (Argument > Adoption > Assessment cascade) enables skills to adapt to project-specific decisions.

### Pain Points Addressed
1. **Inconsistent AI execution:** Free-form markdown interpretation varies across sessions and tools
   - **Impact:** Developer must re-verify and correct AI behavior frequently
   - **Frequency:** Every AI-assisted session

2. **Tool fragmentation:** Each AI tool requires separate prompt/agent configuration
   - **Impact:** Maintenance burden multiplied by number of supported tools
   - **Frequency:** Every KB update

## Target Users &amp; Personas

### Primary Users
**Developer using AI assistants:** Uses Claude Code, Copilot, Cursor, or other AI tools daily for development tasks. Wants consistent, reliable AI behavior when following pair processes.

**Team lead / KB maintainer:** Manages the pair KB for their team. Wants a single source of truth that works across all AI tools without maintaining separate configurations.

## Solution Overview

### Core Solution Approach
Introduce Agent Skills (agentskills.io) into `dataset/.skills/` with a two-dimensional model: **process skills** (from how-to lifecycle) and **capability skills** (from actionable guidelines). Registry-based installation with prefix/flatten configuration distributes skills to each tool's expected folder via canonical + symlink targets.

### Key Capabilities
1. **Registry-based skill installation:** Extend content-ops with `prefix`, `flatten`, `targets` config to install skills to 5 AI tool folders
   - **Value:** Single source, multi-tool distribution with zero duplication

2. **Process skills (11):** Executable versions of how-to phases (implement, review, plan-tasks, etc.)
   - **Value:** Consistent, structured execution of development lifecycle phases

3. **Capability skills (18):** Assessment, workflow, compliance, and setup skills extracted from actionable guidelines
   - **Value:** Structured decision-making (assess-*), adoption compliance (verify-adoption), artifact production (verify-*, write-issue), one-time config (setup-*)

4. **Navigator skill (/next):** Reads project state, suggests next skill to invoke
   - **Value:** Entry point for skill-enabled assistants, replaces manual task selection

### Solution Differentiators
- Follows open standard (agentskills.io) — not proprietary
- Zero duplication: skill operates, how-to orchestrates, guideline educates
- Incremental adoption: skills coexist with existing documentation

## Epic Breakdown

### User Stories — Execution Order

#### Circle 1: Sprint Cycle (P0)

- [x] **#98** [Skill infrastructure + navigator (/next)](https://github.com/foomakers/pair/issues/98) — L(5) — Foundation: registry extension, .skills/ structure, /next skill, AGENTS.md update
- [x] **#99** [Implement task with skills](https://github.com/foomakers/pair/issues/99) — L(5) — /implement, /verify-quality, /record-decision + thin how-to-10. Depends on #98. Optional composition: /assess-stack (#104), /verify-adoption (#105)
- [x] **#100** [Code review with skills](https://github.com/foomakers/pair/issues/100) — M(3) — /review, /verify-done + thin how-to-11. Depends on #99.
- [x] **#101** [Sprint planning with skills](https://github.com/foomakers/pair/issues/101) — L(5) — /refine-story, /plan-tasks, /write-issue + thin how-to-08,09. Depends on #98.

#### Circle 2: Bootstrap &amp; Planning (P1)

- [x] **#102** [Bootstrap core with skills](https://github.com/foomakers/pair/issues/102) — M(3) — /specify-prd, /bootstrap, /setup-pm + thin how-to-01,02. Depends on #98, #99 (/record-decision). **DONE — PR #116 merged 2026-02-13**
- [x] **#104** [Assessment skills](https://github.com/foomakers/pair/issues/104) — L(5) — 8 assess-* skills (/assess-stack lifecycle-spanning) with resolution cascade. Depends on #98, #99, #102 **DONE — PR #117 merged 2026-02-13**
- [x] **#103** [Strategic planning process skills](https://github.com/foomakers/pair/issues/103) — L(5) — /plan-initiatives through /plan-stories + thin how-to-03..07. Depends on #98. **DONE — PR #118 merged 2026-02-13**
- [x] **#105** [Remaining capability skills + /verify-adoption](https://github.com/foomakers/pair/issues/105) — L(5) — /estimate, /setup-gates, /manage-flags, /assess-debt, /assess-code-quality, /verify-adoption + /next update + ADL docs + prompt deletion. Depends on #98, #99, #104 **DONE — PR #119 merged 2026-02-14**

### Epic Acceptance Criteria
- [x] **AC1:** 30 SKILL.md files exist in `dataset/.skills/` with valid frontmatter
- [x] **AC2:** `pair install` distributes skills to `.claude/skills/`, `.github/skills/`, `.cursor/skills/`, `.agents/skills/`, `.windsurf/skills/` using canonical + symlink
- [x] **AC3:** How-to files 08-11 are thinned to ~30-40% of current size, referencing skills for operational detail
- [x] **AC4:** /next skill correctly reads project state and suggests appropriate next skill
- [x] **AC5:** Skills follow adoption binding (Argument > Adoption > Assessment cascade)

## Technical Considerations

### Architecture Overview
- **Source:** `dataset/.skills/` — skills in categories (`process/`, `capability/`) or top-level (`next/`)
- **Registry config:** `prefix: pair`, `flatten: true` → `pair-process-implement/SKILL.md`
- **Targets:** `.claude/skills/` (canonical), others as directory-level symlinks
- **SKILL.md format:** YAML frontmatter (description, arguments, allowed-tools, fork) + markdown body

### Technical Requirements
- **content-ops extension:** Support `prefix`, `flatten`, `targets` in registry config
- **Symlink support:** Directory-level symlinks from `.github/skills/` → `.claude/skills/` etc.
- **Backward compatibility:** Existing how-to documents remain readable as standalone documentation
- **No external references:** .pair/ remains self-consistent

### Technical Risks
| Risk | Impact | Probability | Mitigation Strategy |
|------|---------|-------------|-------------------|
| AI tools don't support SKILL.md as expected | High | Low | agentskills.io is a validated open standard |
| How-to thinning breaks non-skill assistants | Medium | Medium | How-to retains orchestration, readable standalone |
| Registry extension complexity | Medium | Low | Generic feature, not skills-specific |

## Timeline &amp; Roadmap

### Development Phases
**Circle 1: Sprint Cycle (P0)** — Stories #98, #99, #100, #101
- Infrastructure + 9 skills covering daily development workflow
- Skills: verify-quality, verify-done, record-decision, write-issue, next, implement, review, plan-tasks, refine-story
- **Progress: 4/4 stories completed. Circle 1 COMPLETE.**

**Circle 2: Bootstrap &amp; Planning (P1)** — Stories #102, #104, #103, #105
- 21 skills covering bootstrap, assessment, compliance, and strategic planning
- Skills: specify-prd, bootstrap, 8 assess-*, setup-pm, plan-initiatives, map-subdomains, map-contexts, plan-epics, plan-stories, estimate, assess-debt, assess-code-quality, setup-gates, manage-flags, verify-adoption
- **Progress: 4/4 stories completed. Circle 2 COMPLETE.**

### Critical Path Dependencies
- [x] **content-ops registry extension** must be completed before any skill installation works
  - **Required by:** #98 — DONE
- [x] **dataset/.skills/ directory structure** must exist before writing skills
  - **Required by:** #98 — DONE

## Risk Management

### Business Risks
| Risk | Impact | Probability | Mitigation Strategy | Owner |
|------|---------|-------------|-------------------|-------|
| Low adoption if skills don't improve consistency | Medium | Low | Validate with Circle 1 before expanding | @rucka |
| Breaking existing workflows | High | Low | Incremental migration, how-to stays readable | @rucka |

---

### Change Log
| Date | Change | Reason | Updated By |
|------|---------|---------|------------|
| 2025-02-08 | Epic creation | Design spec complete, ready for implementation | @rucka |
| 2025-02-08 | Restructured to 8 stories | INVEST validation: split XL stories #102 and #103 into 4 smaller stories (≤L) | @rucka |
| 2026-02-09 | Skills 29→30, /verify-adoption + /assess-stack | Developer review: added /verify-adoption (adoption compliance) to #105, /assess-stack (lifecycle-spanning) to #104. Updated counts, dependencies, optional compositions in #99/#100 | @rucka |
| 2026-02-11 | #98 + #99 completed, status → In Progress | #98 merged (skill infrastructure + /next). #99 merged (PR #107: /implement, /verify-quality, /record-decision + how-to-10 thinning + relative link conversion). Circle 1 P0: 2/4 done. #100, #101, #102, #103 now unblocked. | @rucka |
| 2026-02-11 | /next moved to top-level | Moved `.skills/navigator/next/` → `.skills/next/` for simpler naming (`pair-next` instead of `pair-navigator-next`). Updated AC1 and architecture paths. | @rucka |
| 2026-02-12 | P0 Circle 1 COMPLETE (4/4) | #100 merged (PR #109: /review, /verify-done + how-to-11 thinning). #101 merged (PR #110: /refine-story, /plan-tasks, /write-issue + how-to-08,09 thinning + markdownlint tooling + handler refactoring). All daily development workflow skills delivered. | @rucka |
| 2026-02-13 | #102 completed, Circle 2: 1/4 | #102 merged (PR #116: /specify-prd, /bootstrap, /setup-pm + how-to-01,02 thinning + /implement inter-task confirmation). Bootstrap lifecycle complete. #103 and #104 now unblocked. | @rucka |
| 2026-02-13 | #103 + #104 completed, Circle 2: 3/4 | #104 merged (PR #117: 8 assess-* skills with resolution cascade). #103 merged (PR #118: /plan-initiatives, /map-subdomains, /map-contexts, /plan-epics, /plan-stories + how-to 03-07 thinning + /implement fix). Strategic planning lifecycle complete. Only #105 remaining. | @rucka |
| 2026-02-14 | #105 completed, EPIC DONE (8/8) | #105 merged (PR #119: 6 remaining capability skills + /verify-adoption + /next 30-skill update + ADL docs + prompt deletion + skills-guide + /review Phase 6 merge/cascade). All 30 skills delivered. Circle 2 COMPLETE. Epic closed. | @rucka |




Risk	Impact	Probability	Mitigation Strategy
AI tools don't support SKILL.md as expected	High	Low	agentskills.io is a validated open standard
How-to thinning breaks non-skill assistants	Medium	Medium	How-to retains orchestration, readable standalone
Registry extension complexity	Medium	Low	Generic feature, not skills-specific

Risk	Impact	Probability	Mitigation Strategy	Owner
Low adoption if skills don't improve consistency	Medium	Low	Validate with Circle 1 before expanding	@rucka
Breaking existing workflows	High	Low	Incremental migration, how-to stays readable	@rucka

Date	Change	Reason	Updated By
2025-02-08	Epic creation	Design spec complete, ready for implementation	@rucka
2025-02-08	Restructured to 8 stories	INVEST validation: split XL stories #102 and #103 into 4 smaller stories (≤L)	@rucka
2026-02-09	Skills 29→30, /verify-adoption + /assess-stack	Developer review: added /verify-adoption (adoption compliance) to #105, /assess-stack (lifecycle-spanning) to #104. Updated counts, dependencies, optional compositions in #99/#100	@rucka
2026-02-11	#98 + #99 completed, status → In Progress	#98 merged (skill infrastructure + /next). #99 merged (PR #107: /implement, /verify-quality, /record-decision + how-to-10 thinning + relative link conversion). Circle 1 P0: 2/4 done. #100, #101, #102, #103 now unblocked.	@rucka
2026-02-11	/next moved to top-level	Moved `.skills/navigator/next/` → `.skills/next/` for simpler naming (`pair-next` instead of `pair-navigator-next`). Updated AC1 and architecture paths.	@rucka
2026-02-12	P0 Circle 1 COMPLETE (4/4)	#100 merged (PR #109: /review, /verify-done + how-to-11 thinning). #101 merged (PR #110: /refine-story, /plan-tasks, /write-issue + how-to-08,09 thinning + markdownlint tooling + handler refactoring). All daily development workflow skills delivered.	@rucka
2026-02-13	#102 completed, Circle 2: 1/4	#102 merged (PR #116: /specify-prd, /bootstrap, /setup-pm + how-to-01,02 thinning + /implement inter-task confirmation). Bootstrap lifecycle complete. #103 and #104 now unblocked.	@rucka
2026-02-13	#103 + #104 completed, Circle 2: 3/4	#104 merged (PR #117: 8 assess-* skills with resolution cascade). #103 merged (PR #118: /plan-initiatives, /map-subdomains, /map-contexts, /plan-epics, /plan-stories + how-to 03-07 thinning + /implement fix). Strategic planning lifecycle complete. Only #105 remaining.	@rucka
2026-02-14	#105 completed, EPIC DONE (8/8)	#105 merged (PR #119: 6 remaining capability skills + /verify-adoption + /next 30-skill update + ADL docs + prompt deletion + skills-guide + /review Phase 6 merge/cascade). All 30 skills delivered. Circle 2 COMPLETE. Epic closed.	@rucka

Uh oh!

Agent Skills in Knowledge Base #97

Description

Epic Information

Epic Statement

Epic Context

Business Value & Objectives

Primary Business Goals

Success Metrics (KPIs)

Problem Statement & Market Opportunity

Current State

Target State

Pain Points Addressed

Target Users & Personas

Primary Users

Solution Overview

Core Solution Approach

Key Capabilities

Solution Differentiators

Epic Breakdown

User Stories — Execution Order

Circle 1: Sprint Cycle (P0)

Circle 2: Bootstrap & Planning (P1)

Epic Acceptance Criteria

Technical Considerations

Architecture Overview

Technical Requirements

Technical Risks

Timeline & Roadmap

Development Phases

Critical Path Dependencies

Risk Management

Business Risks

Change Log

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions