---

name: knowns.doc description: Use when working with Knowns documentation - viewing, searching, creating, or updating docs

Working with Documentation

Navigate, create, and update Knowns project documentation.

Announce at start: "I'm using the knowns.doc skill to work with documentation."

Core principle: SEARCH BEFORE CREATING - avoid duplicates.

Quick Reference

Copy# List all docs
knowns doc list --plain

# View doc (auto-handles large docs)
knowns doc "<path>" --plain --smart

# Search docs
knowns search "<query>" --type doc --plain

# Create doc
knowns doc create "<title>" -d "<description>" -t "tags" -f "folder"

# Update doc
knowns doc edit "<path>" -c "content"      # Replace
knowns doc edit "<path>" -a "content"      # Append
knowns doc edit "<path>" --section "2" -c "content"  # Section only

Reading Documents

Always use --smart flag:

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

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

Creating Documents

Step 1: Search First

Copyknowns search "<topic>" --type doc --plain

Don't duplicate. Update existing docs when possible.

Step 2: Choose Location

Step 3: Create

Copyknowns doc create "<title>" \
  -d "<brief description>" \
  -t "tag1,tag2" \
  -f "folder"  # optional

Step 4: Add Content

Copyknowns doc edit "<path>" -c "$(cat <<'EOF'
# Title

## 1. Overview
What this doc covers.

## 2. Details
Main content.

## 3. Examples
Practical examples.
EOF
)"

Updating Documents

View First

Copyknowns doc "<path>" --plain --smart
knowns doc "<path>" --toc --plain  # For large docs

Update Methods

Section edit is most efficient - less context, safer.

Copy# Update just section 3
knowns doc edit "<path>" --section "3" -c "## 3. New Content

Updated section content..."

Document Structure

Use numbered headings for --section to work:

Copy# Title (H1 - only one)

## 1. Overview
...

## 2. Installation
...

## 3. Configuration
...

Remember

• Search before creating (avoid duplicates)
• Always use --smart when reading
• Use --section for targeted edits
• Use numbered headings
• Reference docs with @doc/<path>