knowledge

What this skill does

# Knowledge: Capture, Summarize, and Organize

Manage a personal knowledge base that extracts content from artifacts, generates summaries, and organizes entries into fluid categories.

**When to activate this skill:**

1. **Explicit knowledge operations:** the user says "save this", "add to knowledge", "capture this article", "summarize this video", "sort knowledge", "organize categories", "import knowledge", etc.

2. **Proactive recall:** the user asks about ANY topic where the knowledge base might have relevant entries. This includes general questions like "what's a good workout routine", "how should I approach this design problem", "what do I know about sleep training", etc. When in doubt, check the knowledge base -- it is an extension of memory. Search it whenever the user's question touches a topic that could plausibly have been captured previously.

## Configuration

### Knowledge Base Path

The knowledge base path is not hardcoded. On first invocation:

1. **Check agent memory** for a previously stored knowledge base path.
2. **If no path is stored**, ask the user. Suggest `~/Documents/knowledge/` or a sensible default.
3. **Save the chosen path** to the agent's persistent memory so it persists across sessions.
4. **On subsequent invocations**, read the stored path. Do not ask again unless the path no longer exists.

### Knowledge Index in Agent Memory

The agent's persistent memory should contain a lightweight index of the knowledge base so that category awareness is always in context — even before this skill is activated. This is what makes proactive recall possible.

After any operation that changes the knowledge base structure (adding entries, sorting, creating/splitting/merging/renaming categories), update the index in agent memory. The index should look approximately like this:

```
## Knowledge Base
Path: ~/Documents/knowledge/
Categories:
- fitness: exercise routines, nutrition, recovery
- parenting: child development, sleep training, education approaches
- software-design: architecture patterns, API design, system modeling
- industrial-design: product design, materials, manufacturing
Unsorted: 3 entries
```

Keep the index under ~20 lines. Update it immediately after any structural change.

### Conventions

- **Date format:** YYYY-MM-DD (ISO 8601 date only)
- **Filename format:** `{descriptive-slug}--{YYYY-MM-DD}.md`
  - Slug: lowercase, hyphenated, 3-6 words describing the content
  - Raw and summary files for the same artifact share the same filename
- **Summary length:** 100-400 words

## Directory Structure

```
{knowledge-base-path}/
  README.md
  CHANGELOG.md
  unsorted/
    raw/
    summary/
  {category}/
    _category.md
    raw/
    summary/
```

Category directories are created on demand when knowledge is sorted into them.

### First-Run Initialization

On first invocation:
1. Resolve the knowledge base path (see Configuration above).
2. If `README.md` does not exist at the knowledge base path, create:
   - `README.md` (see README Template below)
   - `CHANGELOG.md` with an initial entry
   - `unsorted/raw/` and `unsorted/summary/` directories (use `mkdir -p` via Bash)
3. Save the resolved path to agent memory if not already stored.

### Version Control

If git is available and the knowledge base directory is not already a git repository, initialize one (`git init`). The knowledge base benefits from version control — it provides history for category reorganizations, a safety net for bulk imports, and makes it easy to sync across machines.

After meaningful operations (adding knowledge, sorting, reorganizing), commit the changes with a short descriptive message. Keep commits atomic: one commit per logical operation rather than batching unrelated changes. Do not push unless the user has configured a remote and asks to push.

---

## File Formats

### Raw File

```markdown
---
title: "{Human-readable title}"
source: "{URL, file path, or description of origin}"
---

{Full extracted content. Preserve original structure where possible.}
```

The filename carries the ID and date (`{slug}--{YYYY-MM-DD}.md`). No need to duplicate them in frontmatter.

Rules:
- Preserve content faithfully. Do not editorialize.
- For YouTube transcripts, clean auto-sub artifacts but keep `[HH:MM:SS]` timestamps at paragraph boundaries.
- For URLs, strip navigation, ads, and boilerplate. Keep the article body.

### Summary File

```markdown
---
title: "{Human-readable title}"
source: "{URL, file path, or description of origin}"
---

## Summary

{2-4 paragraphs capturing the main ideas, arguments, or content.
Write in plain, direct prose.}

## Key Points

- {Bullet point}

## Takeaways

{1-2 sentences on why this matters or how it connects to broader themes.}
```

The filename carries the ID and date. The corresponding raw file is always at `../raw/{same-filename}`. Category directories and descriptive filenames provide the semantic structure — no tags needed.

Rules:
- When generating, read the full raw content first. Capture the core argument, not surface details.
- Cross-entry relationships are discovered at recall time by the agent (via search, category context, or embeddings) rather than stored in individual files.

### _category.md

```markdown
---
category: {category-slug}
description: "{One-sentence scope definition}"
---

## {Category Name}

{1-3 sentences defining what belongs in this category and what does not.
Be specific enough to resolve ambiguity when sorting.}

## Notes

{Optional guidance on navigating this category, notable themes,
or conventions specific to this domain.}
```

### CHANGELOG.md Format

```markdown
# Knowledge Base Changelog

## YYYY-MM-DD

### Added
- [{id}] "{title}" from {source_type} -- placed in `{category}/`

### Moved
- [{id}] moved from `{old-category}/` to `{new-category}/`

### Categories
- Created `{category-name}`: {description}
- Renamed `{old-name}` to `{new-name}`
- Split `{old-name}` into `{new-name-1}` and `{new-name-2}`
- Merged `{name-1}` and `{name-2}` into `{new-name}`
```

Group entries under the current date heading. If today's heading exists, append to it.

---

## Core Abilities

### Ability 1: Create Knowledge from an Artifact

When the user provides a URL, YouTube link, file path, or content to capture:

**Step 1: Detect source type.**
- YouTube URL: contains `youtube.com/watch`, `youtu.be/`, or `youtube.com/shorts/`
- General URL: starts with `http://` or `https://`
- File path: exists on local filesystem
- Pasted text: inline content provided directly

**Step 2: Extract raw content.**

| Source | Method |
|--------|--------|
| URL | `WebFetch(url, "Extract the main article content of this page as plain text")` |
| YouTube | Bash: `yt-dlp --write-auto-sub --sub-lang "en" --skip-download --print title --print description -o "/tmp/yt-%(id)s" "{url}"` then Read the `.vtt` file and clean it (see transcript cleaning below) |
| Local file | `Read(filepath)` |
| Audio | Bash: `whisper "{path}" --output_format txt` if available; otherwise note as placeholder |
| Pasted text | Use directly |

**YouTube transcript cleaning:**
1. Remove VTT headers (`WEBVTT`, `Kind:`, `Language:`)
2. Remove timestamp lines (lines matching `XX:XX:XX.XXX --> XX:XX:XX.XXX`)
3. Remove duplicate consecutive lines
4. Collapse blank lines
5. Insert `[HH:MM:SS]` markers approximately every 60 seconds as paragraph breaks
6. Clean up via Bash pipeline, then read and format the result
7. Clean up temporary files in `/tmp/`

**Step 3: Generate descriptive slug.** Read the extracted content and produce a 3-6 word lowercase hyphenated slug. Examples:
- `deep-work-productivity-strategies--2026-02-27`
- `react-server-components-explained--2026-02-27`
- `infant-sleep-training-methods--2026-02-27`

**Step 4: Check for duplicates.** Grep across `**/raw/*.md` for the source URL in frontmatter. If found, warn the user and ask whether to overwrite or create a suffixed version.

**Step 5: Determine placement.** Consult the knowledge index in