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

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

# 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:

# 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

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

# 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

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:

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

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:

MCP is recommended when available - faster, structured output.

Supported Platforms