# Skills System

AI workflow instructions with kn-* namespace

## Skills System

Skills are AI workflow instructions using the `/kn-*` namespace. Define once, use across platforms.

## Overview

Skills are embedded in the Knowns binary and synced to platform-specific directories during `knowns init` or `knowns sync`. They provide:

- **Standardized workflows** \- task, spec, commit, research, debug
- **Multi-platform support** \- Claude Code, Kiro, Cursor, Gemini CLI, and more
- **SDD integration** \- spec-driven development with auto-sync
- **Memory integration** \- read and write project/global memory across sessions
- **MCP-first** \- prefer MCP tools when available, CLI as fallback

## Built-in Skills

| Skill | Description |
| --- | --- |
| `/kn-init` | Initialize session, read docs, load memory |
| `/kn-spec <name>` | Create spec document (SDD) |
| `/kn-plan [task]` | Create implementation plan |
| `/kn-go <spec>` | Full pipeline: spec → tasks → implement → commit |
| `/kn-research` | Explore codebase patterns |
| `/kn-implement <id>` | Implement a task with tracking |
| `/kn-verify` | Check ACs, references, SDD coverage |
| `/kn-commit` | Create conventional commit |
| `/kn-extract` | Extract patterns to docs and memory |
| `/kn-doc` | Manage documentation |
| `/kn-template` | Run code templates |
| `/kn-review` | Multi-perspective code review (P1/P2/P3) |
| `/kn-debug` | Structured debugging: triage → fix → learn |

## How Skills Work

1. Skills are embedded in the Knowns binary as SKILL.md files
2. During `knowns init`, skills are copied to the platform directories you selected
3. `knowns sync --skills` re-syncs skills from the binary to platform dirs
4. AI assistants discover skills from their platform directory

## `/kn-init`

Initialize a session by reading project context.

**What it does:**

1. Lists all documentation
2. Reads core docs (README, ARCHITECTURE, CONVENTIONS)
3. Loads project memory and critical learnings
4. Checks for in-progress tasks and active timers
5. Summarizes project context

```bash
# Equivalent CLI:
knowns doc list --plain
knowns doc "README" --plain --smart
knowns task list --status in-progress --plain
knowns time status
```

## `/kn-spec <name>`

Create a spec document for spec-driven development.

**Use when:** Starting a large feature that needs requirements defined first.

**What it does:**

1. Asks: "What feature are you speccing?"
2. Generates spec at `.knowns/docs/specs/<name>.md`
3. Includes: Overview, Requirements, ACs, Scenarios
4. Sets `status: draft`
5. When approved, suggests: "Create tasks? (`/kn-plan --from @doc/specs/<name>`)"

**Spec format:**

```
---
title: User Authentication
type: spec
status: draft # draft → approved → implemented
---

## Overview

Brief description of the feature.

## Requirements

### REQ-1: User Login

- [ ] User can login with email/password
- [ ] Invalid credentials show error
- [ ] Session expires after 24h

## Scenarios

- Happy path: ...
- Edge cases: ...
```

## `/kn-plan [task]`

Create an implementation plan.

**Two modes:**

```bash
# Plan for existing task
/kn-plan 42

# Generate tasks from spec (SDD)
/kn-plan --from @doc/specs/user-auth
```

**From spec:** Breaks requirements into tasks, each with:

- Title from requirement
- ACs copied from spec
- `spec: specs/user-auth` field for auto-sync

## `/kn-research`

Explore codebase before implementing.

**Use when:**

- Unfamiliar with codebase area
- Adding new patterns
- Making architectural decisions

**What it does:**

1. Searches documentation for topic
2. Checks project memory for prior patterns and decisions
3. Reviews similar completed tasks
4. Analyzes codebase patterns
5. Documents findings

## `/kn-implement <id>`

Implement a task with full tracking.

**Phase 1: Take Ownership**

```bash
knowns task <id> --plain
knowns task edit <id> -s in-progress -a @me
knowns time start <id>
```

**Phase 2: Research**

- Follow ALL `@doc/...` and `@task-...` references
- If task has `spec:` field, read the spec

**Phase 3: Implement**

```bash
# Check AC only AFTER work is done
knowns task edit <id> --check-ac 1
knowns task edit <id> --append-notes "✓ Done: feature X"
```

**Phase 4: Complete**

```bash
knowns time stop
knowns task edit <id> -s done
```

**SDD auto-sync:** When you check an AC on a task linked to a spec, the matching AC in the spec is also updated.

## `/kn-verify`

Run SDD verification and coverage check.

**What it checks:**

- All ACs completed
- References resolve (`@doc/...`, `@task-...`)
- Spec coverage (tasks linked to specs)

**CLI equivalent:**

```bash
knowns validate --sdd
```

## `/kn-extract`

Extract reusable patterns from completed tasks.

**Good candidates:**

- Reusable code patterns
- Error handling approaches
- Integration patterns
- Performance solutions

Extraction can also save a concise memory entry so future agents can reuse the lesson without rereading the full task history.

## `/kn-debug`

Structured debugging workflow.

**Process:** triage → reproduce → fix → verify → learn

Captures debugging learnings as memory entries for future reference.

## SKILL.md Format

```
---
name: kn-init
description: Initialize session - read docs, load memory, understand project
---

# Session Init

Instructions for the AI workflow...
```

### Frontmatter

| Field | Description |
| --- | --- |
| `name` | Skill identifier |
| `description` | Short description shown in skill list |

## Synced Locations

```
.knowns/skills/              # Source of truth (embedded in binary)

# Auto-synced to platform directories:
.claude/skills/              # Claude Code
.agent/skills/               # Kiro / Antigravity
```

## CLI Commands

```
# Sync skills + instructions from binary to platform dirs
knowns sync

# Sync skills only
knowns sync --skills

# Sync instruction files only
knowns sync --instructions

# Sync a specific platform's instruction file
knowns sync --instructions --platform claude
```

## Memory Integration

All skills participate in the memory loop:

- **Read skills** (init, research, plan, spec, go, review, debug): search memory via unified search
- **Write skills** (implement, extract, debug): save patterns/decisions/failures with `memory({ action: "add", layer: "project" })`
- The global rule in KNOWNS.md encourages all skills to save knowledge as it emerges

## MCP vs CLI in Skills

Skills use MCP tools when available, with CLI as fallback:

| Feature | MCP | CLI |
| --- | --- | --- |
| Tasks | `tasks({ action: "get/update" })` | `task list`, `task edit` |
| Docs | `docs({ action: "get/update" })` | `doc`, `doc edit` |
| Memory | `memory({ action: "add/list" })` | `memory list`, `memory add` |
| Time | `time({ action: "start/stop" })` | `time start`, `time stop` |
| Validate | `validate({ scope: "sdd" })` | `validate --sdd` |
| Templates | `templates({ action: "run" })` | `template run` |
| Search | `search({ action: "search" })` | `search "query" --plain` |

**MCP is recommended** when available - faster, structured output.

## Supported Platforms

| Platform | Skills Location | MCP |
| --- | --- | --- |
| **Claude Code** | `.claude/skills/` | Full |
| **Kiro** | `.agent/skills/` | Full |
| **Antigravity** | `.agent/skills/` | Full |
| **Cursor** | `.cursor/rules/` | Full |
| **Gemini CLI** | `~/.gemini/commands/` | Full |
| **Cline** | `.clinerules/` | Full |
| **Continue** | `.continue/` | Full |
| **Windsurf** | `.windsurfrules` | Limited |
| **GitHub Copilot** | `.github/copilot-instructions.md` | Instructions only |