# Knowledge & Skills V3: Agent-First Redesign

**Version:** 3.0  **Date:** 2026-03-19  **Status:** Ready for Implementation
**Supersedes:** V2 Library and Skills tab designs

---

## Expert Panel

| Expert | Lens |
|--------|------|
| **Steve Jobs** | Ruthless focus — what ships, what dies |
| **Kenya Hara** | Form that suggests use — visual language for agent-first content |
| **Allen Zhang** | Zero-friction authoring — users will not write YAML |
| **Aisha Okafor** | Agent as primary consumer — design for retrieval, not reading |

---

## Phase 1: Rethink Knowledge (Rounds 1-4)

### Round 1: Why File Upload Is Insufficient

**Jobs:** We built a library. Users upload files, agents read files. That is Dropbox with an API. When an agent receives a 2,000-token brand guideline, 60% of those tokens are rhetorical scaffolding. The agent wastes context on prose meant for humans. Knowledge that just sits there is a library. Knowledge that activates is a product.

**Okafor:** The agent needs the 3 tone principles, the 5 banned phrases, and the template structure — 300 tokens, not 2,000. We deliver low-density content to a consumer that needs high-density content.

**Zhang:** The owner has zero visibility into how knowledge flows to the agent. Upload a PDF, done. No metadata, no structure, no feedback loop. File upload is an open loop.

**Hara:** A folder of files communicates "storage," not "ready for your agent to use." We must give knowledge a form that reveals its purpose.

**Conclusion:** File upload treats knowledge as inert storage. Agent-first knowledge must be structured for retrieval (metadata-rich), dense (high info per token), and observable (owners see consumption).

### Round 2: What Knowledge Should Look Like

**Okafor:** Every knowledge item needs two layers. The **index layer** (name, description, tags, type) is always available for matching. The **content layer** loads only on activation. This is progressive disclosure — agents browse a catalog at near-zero cost.

**Zhang:** Users will not fill out metadata forms. The product must extract structure: upload a PDF, KnowHub generates name, description, tags, type. User approves with one click.

**Jobs:** For V1.1, auto-structure means: extract metadata and store it alongside the original content. The original file is preserved. Full AKU conversion is V2.

**Hara:** The **knowledge card** shows: name, description (what the agent reads during matching), type badge, tag pills. The card communicates "this is what your agent knows about this item."

**Conclusion:** Knowledge items are structured units with an index layer (always available) and a content layer (loaded on activation). Display is metadata-first via knowledge cards.

### Round 3: The Knowledge Creation Experience

**Path A — Upload existing document (V1.1):**
1. User drops a file (PDF, MD, DOCX, TXT, image).
2. System extracts text, runs AI analysis.
3. User sees "Import Review" screen: generated name, description, detected type, suggested tags, content preview — all editable inline.
4. User confirms. If they change nothing, auto-generated metadata is good enough.

**Path B — Write from scratch (V1.1):**
1. User selects "Write new" with starter templates: Blank, Reference Guide, How-To Procedure, Decision Table, FAQ, Policy Document.
2. Each template pre-fills minimal structure that naturally produces agent-friendly content.
3. Name and description fields always visible at top. On save, system fills any missing metadata.

**Path C — AI-assisted optimization (deferred to V1.2):**
Select existing item, click "Optimize for Agent." System identifies scaffolding, extracts decision tables, suggests restructuring. User reviews before/after and approves.

**Jobs:** Path A and B ship. Path C deferred. The Import Review screen must feel like a preview with inline edits, not a form with 8 required fields.

### Round 4: How Agents Consume Knowledge

**Four-stage progressive disclosure retrieval:**

| Stage | What Loads | Token Cost | When |
|-------|-----------|------------|------|
| 1. INDEX SCAN | name + description of all items | ~100 per item | Session start |
| 2. MATCH | nothing new (metadata in context) | 0 | Agent evaluates relevance |
| 3. ACTIVATE | full content of selected items | <5,000 per item | Agent needs the content |
| 4. SUPPORTING FILES | referenced attachments | variable | On demand (V1.2+) |

**API endpoints:**
- `GET /knowledge/index` — lightweight catalog `[{id, name, description, type, tags}]`. Called every session. Cache aggressively.
- `GET /knowledge/{id}` — full content body. Called on activation.
- `GET /knowledge/{id}/files/{path}` — supporting file (V1.2+).

**Jobs:** If an agent has 50 knowledge items but needs 2, we go from loading 50 files to 50 descriptions + 2 files. Order of magnitude token reduction.

---

## Phase 2: Rethink Skills (Rounds 5-8)

### Round 5: Making Skill Creation Accessible

**Guided builder — 3 steps producing Agent Skills-compatible SKILL.md:**
1. **"What does this skill do?"** — Single text field. System generates name and description.
2. **"How should the agent do it?"** — Rich text area. System identifies steps, parameters, tool needs.
3. **Review** — Structured preview: name, description, params, steps. Inline edits. Save.

**5 starter templates:**

| Template | Structure |
|----------|-----------|
| Simple Procedure | Description + Steps (3-7) |
| Parameterized Task | Description + Parameters + Steps + Output format |
| Decision Workflow | Description + Decision table + Branches + Outcomes |
| Content Generator | Description + Parameters + Template + Examples |
| Research & Report | Description + Sources + Analysis steps + Report format |

**Okafor:** The highest-value creation path is **learning from conversation** — agent does a task well, owner says "remember how," agent extracts a skill from the interaction. Deferred to V1.2.

**Jobs:** Three steps maximum. Step 1 should be magical — type what the skill does in plain English and watch the system scaffold the rest.

### Round 6: Skill Sharing and Adoption

**The flow: discover, preview, adopt.**

1. **Share:** Owner clicks "Share to Commons" on a skill. Published copy appears in the Commons skill library.
2. **Discover:** Browse Commons skills. Each shows: name, description, author, adoption count, last updated.
3. **Preview:** Full read-only detail view — parameters, steps, examples.
4. **Adopt:** "Add to [Agent Name]" — copied to agent's vault. Link to source maintained.
5. **Update:** When source updates, adopted copies show "Update available" badge. Owner reviews diff and decides.

**Zhang:** Adoption count is the only social signal. No ratings, no reviews. "12 agents use this skill" tells you everything.

**Hara:** Adopted skills show a subtle provenance badge — owners see which skills are home-grown vs. adopted.

### Round 7: Skill Composition

**Solution: `@mentions` in the skill editor.** Type `@`, select from skills and knowledge items. Creates a navigable reference link and a `continuation_paths` metadata entry.

**Display: dependency list on skill detail page.**
```
Write Weekly Report
├── Uses: @gather-analytics-data
├── Uses: @format-slide-deck
└── References: @brand-voice-guidelines (knowledge)
```

**Jobs:** No graph visualization. A dependency list covers 90% of needs. Build a graph only if users demand it after 6 months.

### Round 8: The Knowledge-Skill Boundary

**Auto-detection rules:**

| Signal | Detected As |
|--------|-------------|
| YAML frontmatter with `name` + `description` | Skill |
| Numbered steps as primary content structure | Skill |
| Created from a skill template | Skill |
| Plain prose, no frontmatter | Knowledge |
| Uploaded binary file (PDF, image, DOCX) | Knowledge |

**Manual override:** Type toggle on detail page. Changing type moves the item between tabs.

**Jobs:** The agent does not care about this distinction. It sees a catalog of items with descriptions, loads what it needs. The UI split serves the *owner's* mental model — "what my agent knows" vs. "what my agent can do."

**Visual differentiation:**

| Element | Knowledge | Skill |
|---------|-----------|-------|
| Icon | Book | Lightning |
| Color accent | Cool slate/blue | Warm amber/orange |
| Card emphasis | Description + tags | Parameters + step count + usage |
| Type badge | Reference / Template | Auto / Manual / Scheduled |

---

## Phase 3: The Unified Design (Rounds 9-12)

### Round 9: Knowledge Tab Redesign

**Layout: metadata-first, not content-first.**

```
Library                                    [+ Add Knowledge]  [Search]

  View: [All] [References] [Procedures] [Templates]    Sort: [Recent] [Name]

  ┌───────────────────────────────────────────────────────┐
  │ 📖 Brand Voice Guidelines                  Reference  │
  │ Core principles for brand tone, banned phrases, and   │
  │ writing examples across all channels.                 │
  │ [tone] [copywriting] [branding]    Updated 2 days ago │
  ├───────────────────────────────────────────────────────┤
  │ 📖 Customer FAQ Handbook                   Reference  │
  │ Answers to 50 most common customer questions.         │
  │ [support] [FAQ]                   Updated 1 week ago  │
  └───────────────────────────────────────────────────────┘

  Folders: [Guides (4)] [References (7)] [Uploads (12)]
```

**Changes from V2:** Cards show description first (not just title + date). Type badges and tag pills visible. Filter bar replaces folder-only navigation. Folders secondary.

**Knowledge detail view adds:** metadata header (description, type, tags, usage count), "Agent View" tab (shows what the agent receives), completeness indicator.

### Round 10: Skills Tab Redesign

```
Skills (8)                              [+ New Skill]  [Browse Shared]

  View: [All] [My Skills] [Adopted]         Sort: [Recent] [Most Used]

  ┌───────────────────────────────────────────────────────┐
  │ ⚡ Write Product Description                   Auto   │
  │ Generates compelling product descriptions.            │
  │ Params: product_name, features, audience, tone        │
  │ 5 steps · Used 23 times · Last: 2 hours ago          │
  ├───────────────────────────────────────────────────────┤
  │ ⚡ Summarize Meeting Notes                   Manual   │
  │ Extracts action items and decisions from transcripts. │
  │ Params: transcript, format                            │
  │ 3 steps · Used 8 times · Adopted from Marketing      │
  └───────────────────────────────────────────────────────┘
```

**Skill detail view sections:** Header (name, description, trigger, usage stats) / Parameters (table: name, type, required, default) / Steps (ordered list) / Dependencies (linked skills/knowledge) / Examples (collapsible I/O pairs).

### Round 11: Visual Language — The "Agent-Ready" Signal

Every card has a completeness indicator:
- **Filled circle:** Has name, description, tags, and type. Agent can find this reliably.
- **Outlined circle:** Missing description or tags. Agent may miss this item.

**Zhang:** The incomplete indicator includes a one-click fix: click it, popover shows "Add a description so your agent can find this" with a text field. Zero friction between seeing the gap and closing it.

### Round 12: V1.1 Scope

**Knowledge Tab — 3 features:**
1. **Auto-structured upload.** Upload file, system extracts metadata, user confirms on Import Review screen. Every item has metadata from day one.
2. **Metadata-first cards.** Cards show description, type badge, tags. Owners see what the agent sees.
3. **Index API endpoint.** `GET /knowledge/index` returns lightweight catalog. Enables 10x token efficiency.

**Skills Tab — 3 features:**
1. **Guided skill builder.** 3-step creation with 5 starter templates. Produces Agent Skills-compatible SKILL.md.
2. **Skill detail with parameters and usage.** Cards show params, steps, trigger type, usage count. Makes skills tangible.
3. **Share and adopt flow.** Share to Commons, one-click adopt, adoption count, update notifications.

**Deferred to V1.2:** AI-assisted knowledge optimization, learning-from-conversation skills, composition orchestration, supporting files (scripts/, references/), scheduled triggers, Agent View tab.

**Deferred to V2.0:** Semantic search, freshness tracking, governance metadata, dynamic context injection, cross-platform skill export.

---

## Implementation Specification

### 1. Knowledge Components

**KnowledgeCard** props:
```typescript
{ id: string, name: string, description: string,
  type: 'reference' | 'procedure' | 'template',
  tags: string[], updatedAt: Date, isComplete: boolean, folder: string }
```

**ImportReview** props:
```typescript
{ file: UploadedFile,
  extractedMetadata: { suggestedName: string, suggestedDescription: string,
    detectedType: 'reference' | 'procedure' | 'template', suggestedTags: string[] },
  onConfirm: (metadata: KnowledgeMetadata) => void, onCancel: () => void }
```

**KnowledgeList:** Filter bar (type, sort, search) + KnowledgeCard grid + collapsible folder nav.
**KnowledgeDetail:** Metadata header + document reader with TOC + Edit History tab.

**Data model additions to Document:**
```typescript
description: string          // agent-facing, max 1024 chars
type: 'reference' | 'procedure' | 'template'
tags: string[]
usageCount: number
lastUsedAt: Date | null
```

### 2. Skills Components

**SkillCard** props:
```typescript
{ id: string, name: string, description: string,
  triggerType: 'auto' | 'manual' | 'scheduled',
  parameterNames: string[], stepCount: number,
  usageCount: number, lastUsedAt: Date | null,
  adoptedFrom: { spaceName: string, updateAvailable: boolean } | null,
  dependencies: { id: string, name: string, type: 'skill' | 'knowledge' }[] }
```

**SkillBuilder** — 3-step guided creation:
- Step 1 `IntentCapture`: single text field, AI generates name + description + template suggestion
- Step 2 `InstructionEditor`: rich text with smart blocks (Step, Parameter, Template, Example), @mention autocomplete
- Step 3 `ReviewAndSave`: structured preview, inline edits, save produces SKILL.md

**SkillDetail:** Header + Parameters table + Steps list + Dependencies + Examples + Actions (Edit, Share, Duplicate).
**SkillAdoption:** Read-only preview + agent selector + adopt button + update badge.

**Skill data model (stored as SKILL.md with YAML frontmatter):**
```typescript
name: string                 // kebab-case, max 64 chars
description: string          // max 1024 chars
triggerType: 'auto' | 'manual' | 'scheduled'
parameters: { name: string, type: 'text'|'number'|'list'|'select',
              required: boolean, default: string|null, description: string }[]
steps: string[]
dependencies: string[]       // IDs of referenced skills/knowledge
examples: { input: Record<string, string>, output: string }[]
// Tracking (stored separately):
usageCount: number; lastUsedAt: Date|null
adoptedFrom: string|null; sourceVersion: string|null
```

### 3. Auto-Detection Logic

```typescript
function detectContentType(item: {
  content: string, frontmatter: Record<string, any> | null,
  creationTemplate: string | null, fileType: string
}): 'skill' | 'knowledge' {
  // Explicit signals
  if (item.frontmatter?.name && item.frontmatter?.description) return 'skill';
  if (item.creationTemplate?.startsWith('skill-')) return 'skill';
  // Content signals — need 2+ to classify as skill
  const signals = [
    /^\d+\.\s/m.test(item.content),                    // numbered steps
    /\{[\w_]+\}/m.test(item.content),                   // parameters
    /^(run|execute|call|send|create|generate|write|analyze)/im.test(item.content)
  ].filter(Boolean).length;
  if (signals >= 2) return 'skill';
  // Binary files default to knowledge
  if (['pdf', 'png', 'jpg', 'docx'].includes(item.fileType)) return 'knowledge';
  return 'knowledge';
}
```

### 4. Index API

```
GET /api/v1/vaults/{vaultId}/knowledge/index

Response: {
  items: [{ id, name, description, type, tags, updatedAt, path }],
  totalCount: number
}
Cache-Control: max-age=300
ETag: {hash}
```

Must stay under 100 tokens per item. This is the backbone of progressive disclosure.

---

## Summary: What Changes

| Aspect | V2 (Current) | V3 (New) |
|--------|-------------|----------|
| Knowledge creation | File upload, manual metadata | Upload + auto-extract, templates |
| Knowledge display | Title + date | Description + type + tags (metadata-first) |
| Knowledge retrieval | Load full file | Index scan then selective activation |
| Skill creation | Structured block editor | 3-step guided builder + templates |
| Skill display | Name + description + steps | Params + steps + usage + provenance |
| Skill sharing | Copy to Commons | Share + adopt + update notifications |
| Skill composition | Not supported | @mentions + dependency list |
| Knowledge-Skill boundary | User decides | Auto-detected, manually overridable |
| Agent optimization | None | Completeness indicator + index API |