Skills System

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

Overview

Skills provide:

• Standardized workflows - task, spec, commit, research
• Multi-platform support - Claude Code, Cursor, Windsurf, Gemini CLI
• SDD integration - spec-driven development with auto-sync

Built-in Skills

/kn-init

Initialize a session by reading project context.

What it does:

1. Lists all documentation
2. Reads core docs (README, ARCHITECTURE, CONVENTIONS)
3. Checks for in-progress tasks and active timers
4. 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. Reviews similar completed tasks
3. Analyzes codebase patterns
4. Documents findings

# Equivalent CLI:
knowns search "<topic>" --type doc --plain
knowns search "<topic>" --type task --status done --plain

/kn-implement <id>

Implement a task with full tracking.

The process:

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)

Output:

SDD Status Report
═══════════════════════════════════════
Specs:    3 total | 2 approved | 1 draft
Tasks:    8 total | 5 done | 2 in-progress
Coverage: 6/8 tasks linked to specs (75%)

⚠️ Warnings:
  - task-12 has no spec reference
  - specs/payment: 1/3 ACs incomplete

✅ Passed:
  - All references resolve
  - specs/user-auth: fully implemented

CLI equivalent:

knowns validate --sdd

/kn-extract

Extract reusable patterns from completed tasks.

Use when: A task contains patterns that could benefit future work.

Good candidates:

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

Process:

# 1. Review completed task
knowns task <id> --plain
 
# 2. Check for existing docs
knowns search "<pattern>" --type doc --plain
 
# 3. Create pattern doc
knowns doc create "Pattern: <Name>" \
  -d "Reusable pattern for <purpose>" \
  -t "pattern" -f "patterns"
 
# 4. Link back to task
knowns task edit <id> --append-notes "📚 Extracted to @doc/patterns/<name>"

/kn-doc

Work with Knowns documentation.

Reading (always use --smart):

knowns doc "<path>" --plain --smart

• Small doc → full content
• Large doc → stats + TOC, then use --section

Creating:

knowns doc create "<title>" -d "<desc>" -t "tags" -f "folder"

Updating:

knowns doc edit "<path>" --section "2" -c "new content"  # Most efficient
knowns doc edit "<path>" -a "appended content"

/kn-template

Run code generation templates.

# List templates
knowns template list
 
# Run template
knowns template run component --name MyComponent

Templates are linked to documentation for AI context.

Source of Truth

.knowns/skills/              # Define here (source of truth)
├── kn-task/SKILL.md
├── kn-spec/SKILL.md
└── custom-skill/SKILL.md

# Auto-sync to platforms
.claude/skills/              # Claude Code
.cursor/rules/               # Cursor (converted)

CLI Commands

# List skills
knowns skill list
 
# Create new skill
knowns skill create my-skill
 
# Sync to platforms
knowns skill sync --all

MCP vs CLI

MCP is recommended when available - faster, structured output.

Supported Platforms