# ADR-001: Knowledge Skills Category and Schema Enrichment

**Date:** 2026-04-07
**Status:** Accepted
**Deciders:** @cwarner

## Context

Harness engineering has 81 behavioral skills covering the full SDLC (planning through deployment), but no mechanism for encoding domain knowledge — design patterns, best practices, and reference material — as skills. The [PatternsDev/skills](https://github.com/PatternsDev/skills) repository demonstrates a successful model: 58 frontend pattern skills following the [agentskills.io](https://agentskills.io) open specification, each covering a single concept with progressive disclosure (metadata → instructions → details).

Comparing harness's skill system against PatternsDev revealed three gaps:

1. **No file-glob activation** — harness dispatches by health signals and keywords, but cannot surface skills based on the files being edited (e.g., `*.tsx` → React patterns)
2. **No conceptual cross-references** — `depends_on` captures execution dependencies, but not "related pattern" relationships useful for discovery
3. **No knowledge skill type** — all 81 skills are behavioral (rigid or flexible). There is no lightweight type for pure-reference content that informs rather than executes

These gaps mean harness agents know _how to do things_ (refactor, test, review) but lack contextual domain knowledge about _what patterns exist_ in the technology being worked on.

## Decision

Implement a two-phase adoption:

### Phase 1: Schema Enrichment

Add three fields to `skill.yaml` (validated in `packages/cli/src/skill/schema.ts`):

- **`paths`** — array of glob patterns indicating which file types activate the skill (e.g., `["**/*.tsx", "**/*.jsx"]`). Dispatch engine (`packages/cli/src/skill/dispatcher.ts`) factors path matches into skill scoring alongside health signals.
- **`related_skills`** — array of skill names representing conceptual relationships (distinct from `depends_on` execution dependencies). Used by recommendation engine for chaining.
- **`metadata`** — object with `author` and `version` fields, supporting upstream attribution for imported skills.

Add progressive disclosure convention to SKILL.md:

- `## Instructions` section (<5K tokens) — agent-facing directives, loaded on activation
- `## Details` section (unlimited) — educational depth, loaded on-demand when agent needs more context

Update `packages/cli/src/skill/skill-executor.ts` to support tiered loading: metadata from skill.yaml (always), Instructions on activation, Details on request.

### Phase 2: Knowledge Skills

Add `type: knowledge` to the skill type enum. Knowledge skills:

- Have no phases, no state persistence, no tool grants
- Use `cognitive_mode: advisory-guide` by default
- Are `tier: 3` by default
- Are surfaced by the dispatch engine via `paths` + `stack_signals` matching, not health signals
- Are injected into agent context as reference material, not executed as workflows

Import PatternsDev's 58 frontend skills as the seed catalog:

- 27 JavaScript pattern skills (prefixed `js-`)
- 19 React pattern skills (prefixed `react-`)
- 11 Vue pattern skills (prefixed `vue-`)
- Each auto-enriched with `cognitive_mode`, `tier`, `stack_signals`, and `paths`
- `metadata.upstream` tracks the source for future sync

Extend the catalog over time with knowledge skills for harness's strong domains (testing patterns, security patterns, infrastructure patterns).

## Alternatives Considered

### Option B: Dual-Format Support (agentskills.io Compatibility Layer)

Add export/import tooling so harness skills could be published in agentskills.io format and consumed by 30+ agent products. Rejected because:

- Export is lossy — cognitive_mode, tier, addresses, and phases have no spec equivalent
- Import produces thin skills requiring manual enrichment
- Two formats to maintain increases ongoing burden
- Portability is not currently a strategic priority — harness's value is in the integrated system (dispatch + graph + mechanical constraints), not in individual skill portability

This option remains viable as a future initiative if ecosystem reach becomes a priority.

## Consequences

### Positive

- Harness skill catalog grows from 81 to 139+ skills, covering frontend patterns for the first time
- Agents gain contextual domain knowledge alongside behavioral capabilities — "how to refactor" + "which React patterns to consider"
- `paths` field enables file-type-aware dispatch, a capability gap identified in the analysis
- `related_skills` creates a lightweight skill relationship graph for discovery
- Progressive disclosure reduces token cost for large skills
- Clean architectural separation: behavioral skills (do things) vs knowledge skills (know things)
- Foundation for expanding knowledge skills into testing, security, and infrastructure domains

### Negative

- Imported content may drift from upstream as PatternsDev evolves — mitigation: `metadata.upstream` field enables periodic sync checks
- Knowledge skills inflate skill count without adding workflow capability — mitigation: dispatcher presents them differently (contextual reference vs actionable recommendation)
- Schema changes require updating skill.yaml across 4 platforms (claude-code, gemini-cli, codex, cursor) — mitigation: phase 1 fields are optional, existing skills remain valid without them

### Neutral

- Knowledge skills establish a precedent for non-behavioral content in the skill catalog, which may lead to future categories (e.g., `type: template`, `type: checklist`)

## Action Items

- [ ] Add `paths`, `related_skills`, `metadata` fields to Zod schema in `packages/cli/src/skill/schema.ts` — owner: @cwarner
- [ ] Update dispatch engine to score `paths` matches — owner: @cwarner
- [ ] Add progressive disclosure (Instructions/Details split) to skill executor — owner: @cwarner
- [ ] Add `type: knowledge` to skill type enum and executor branch — owner: @cwarner
- [ ] Import 58 PatternsDev skills with harness enrichment — owner: @cwarner
- [ ] Backfill `paths` and `related_skills` on existing behavioral skills (gradual) — owner: @cwarner
- [ ] Add roadmap item for this work — owner: @cwarner
