Claude Code Skills

Knowns provides specialized skills for Claude Code that automate common workflows. Skills are invoked using /skill-name syntax.

What are Skills?

Skills are pre-defined workflows that Claude Code executes when you type /knowns.<skill-name>. Each skill follows best practices and ensures consistent behavior across sessions.

Available Skills

/knowns.init

Initialize a session by reading project documentation and understanding current state.

Use when: Starting a new session or switching to a different project area.

What it does:

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

# The skill runs these commands:
knowns doc list --plain
knowns doc "README" --plain --smart
knowns doc "ARCHITECTURE" --plain --smart
knowns task list --status in-progress --plain
knowns time status

/knowns.task <id>

Execute the complete task workflow with proper time tracking and documentation.

Use when: Working on any Knowns task.

Core principle: No implementation without research and approved plan first.

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 (Mandatory)

• Follow ALL @doc/... and @task-... references
• Search for related documentation
• Check similar completed tasks

Phase 3: Plan (Wait for Approval)

knowns task edit <id> --plan $'1. Step one (see @doc/relevant-doc)
2. Step two
3. Add tests
4. Update documentation'

Phase 4: Implement

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

Phase 5: Complete

knowns task edit <id> --notes $'## Summary
What was done and key decisions.'
 
knowns time stop
knowns task edit <id> -s done

/knowns.research <topic>

Understand existing patterns before making changes.

Use when:

• Implementing new features
• Adding new patterns
• Making architectural decisions

What it does:

1. Searches documentation for the topic
2. Reviews similar completed tasks
3. Analyzes codebase patterns
4. Documents findings

# Search docs and tasks
knowns search "<topic>" --type doc --plain
knowns search "<keywords>" --type task --status done --plain
 
# View relevant docs
knowns doc "<path>" --plain --smart

Research Checklist

• Searched documentation
• Reviewed similar completed tasks
• Found existing code patterns
• Identified reusable components
• Noted conventions to follow

/knowns.doc

Work with Knowns documentation efficiently.

Core principle: Search before creating - avoid duplicates.

Reading Documents

Always use --smart flag:

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

• Small doc (≤2000 tokens) → full content
• Large doc → stats + TOC, then use --section

Creating Documents

# 1. Search first
knowns search "<topic>" --type doc --plain
 
# 2. Create with proper location
knowns doc create "<title>" \
  -d "<description>" \
  -t "tag1,tag2" \
  -f "folder"  # patterns, guides, api, etc.
 
# 3. Add content
knowns doc edit "<path>" -c "content..."

Updating Documents

# Section edit (most efficient)
knowns doc edit "<path>" --section "2" -c "new content"
 
# Append
knowns doc edit "<path>" -a "additional content"
 
# Replace all
knowns doc edit "<path>" -c "new content"

/knowns.commit

Generate conventional commit messages for staged changes.

What it does:

1. Analyzes staged changes with git diff --staged
2. Generates commit message following conventional format
3. Shows message for confirmation
4. Commits with approved message

Format

<type>(<scope>): <message title>

<bullet points summarizing what was updated>

Allowed Types

Example

feat(auth): add JWT login flow

- Implemented JWT token validation logic
- Added documentation for the validation component

/knowns.task.brainstorm

Explore approaches when requirements are unclear.

Use when:

• Vague requirements ("make it faster", "improve UX")
• Multiple valid approaches exist
• Significant effort involved
• New territory for the project

The Process

Phase 1: Discovery

• Ask clarifying questions (one at a time)
• Prefer multiple-choice options

Phase 2: Research

knowns search "<topic>" --type doc --plain
knowns search "<keywords>" --type task --status done --plain

Phase 3: Present Options

## Option A: [Name]
- **Approach**: Brief description
- **Pros**: What's good
- **Cons**: What's challenging
- **Effort**: Low/Medium/High
 
## Option B: [Name]
...

Phase 4: Document Decision

• Create task with agreed approach
• Define clear acceptance criteria

/knowns.task.extract <id>

Extract reusable knowledge from completed tasks.

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

Core principle: Only extract generalizable knowledge, not task-specific details.

Good Candidates

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

The Process

# 1. Review 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,<domain>" \
  -f "patterns"
 
# 4. Link back to task
knowns task edit <id> --append-notes "📚 Extracted to @doc/patterns/<name>"

/knowns.task.reopen <id>

Reopen completed tasks with proper tracking.

Use when:

• User requested changes after completion
• Bug found in implementation
• New requirements added

When to Reopen vs Create New

The Process

# 1. Reopen and start timer
knowns task edit <id> -s in-progress
knowns time start <id>
 
# 2. Document reason
knowns task edit <id> --append-notes "🔄 Reopened: <reason>"
 
# 3. Add new requirements
knowns task edit <id> --ac "New requirement"
 
# 4. Complete normally
knowns task edit <id> --check-ac <index>
knowns time stop
knowns task edit <id> -s done

Best Practices

Always Announce

Skills should announce themselves at the start:

"I'm using the knowns.task skill to work on task 42."

Time Tracking

• Always start timer when taking a task
• Always stop timer when completing
• Timer data informs project estimation

Research First

• Read related docs before planning
• Check similar completed tasks
• Understand existing patterns

Plan Before Implementing

• Create implementation plan
• Wait for user approval
• Don't start coding without agreement

Document Decisions

• Check acceptance criteria as completed
• Add implementation notes
• Extract reusable patterns