# Knowledge vs Skills: Merge or Separate? **Decision:** Merge into a single "Knowledge" tab **Date:** 2026-03-19 --- ## Discussion ### Round 1: Are Knowledge and Skills fundamentally different? **Steve Jobs:** Let me ask the simplest question. An agent fetches a file from `knowledge/brand-guidelines.md`. Then it fetches a file from `skills/write-product-description.md`. What did it do differently? Nothing. It read a file. The agent does not care which directory the file lives in. It reads content and acts on it. If the agent treats them identically, why are we telling the user they are different things? **Kenya Hara:** From the user's perspective, the distinction creates a question: "Where do I put this?" A document that explains how to write a good commit message -- is that knowledge or a skill? A coding style guide with step-by-step rules -- knowledge or skill? When the user hesitates, the design has failed. The distinction must be self-evident or it should not exist. **Letta (MemGPT) perspective:** Letta separates procedural memory from archival memory because the *retrieval* patterns differ. Procedural memory is invoked when the agent needs to *do* something. Archival memory is searched when the agent needs to *know* something. This is a meaningful distinction in the agent runtime -- but it is an internal optimization, not a user-facing concept. The user does not need to understand retrieval strategies. **Mem0 perspective:** Mem0 treats everything as memory with metadata. A "skill" is just a memory tagged as procedural. The system handles retrieval routing internally. This keeps the user interface clean and the API simple. Fewer concepts, fewer mistakes. **Allen Zhang:** From the storage perspective, both are files in a Git repo. `knowledge/` and `skills/` are just directories. The `Skill` type in our codebase is derived by parsing markdown frontmatter from files in the `skills/` directory -- the same parsing could happen for files anywhere. The separation is a convention, not a technical boundary. **Verdict:** Skills are a subtype of knowledge. The agent, the storage, and the API treat them the same way. The separation is a UI-level convention that creates more confusion than clarity. --- ### Round 2: How do real users organize reference material vs workflows? **Steve Jobs:** Think about how people actually use Notion. They have a workspace. Inside it, they make pages. Some pages are reference docs. Some are templates. Some are step-by-step runbooks. They are all *pages* in the same sidebar. Nobody creates a separate "Skills" section in their Notion workspace. They use folders, tags, or database properties. The taxonomy is emergent, not imposed. **Kenya Hara:** In Google Drive, you have folders. A company might have `Engineering/Runbooks/` and `Engineering/Reference/`. The container is the same -- a folder. The organization is the user's choice. The tool does not force you to decide if something is a "skill" or a "document" before you can store it. **Allen Zhang:** The critical insight: real-world organization is *continuous*, not *binary*. A reference document might contain procedural steps. A workflow template might include reference tables. Forcing every file into either "knowledge" or "skill" is an artificial constraint that does not match how information actually works. **Letta perspective:** Even in cognitive science, the boundary between declarative and procedural knowledge is fuzzy. Knowing how to ride a bike (procedural) and knowing the rules of grammar (declarative, but applied procedurally) -- the categories bleed into each other. Forcing a binary split on the user is asking them to solve a problem that cognitive scientists have not solved. **Verdict:** Users organize by topic/project/domain, not by "is this a fact or a procedure." Our UI should reflect that. --- ### Round 3: The case for merging into one "Knowledge" section **Steve Jobs:** Here is what I want. One tab. Called "Knowledge." It shows a folder browser. You can put anything in it -- documents, guides, templates, runbooks, skill files. If a file happens to have structured frontmatter (name, parameters, steps), we render it with a nice skill card automatically. No manual categorization. No separate tab. No confusion. **Allen Zhang:** Look at the real data from openclaw/clawmem. Both `knowledge/` and `skills/` directories are empty. Nobody has used either feature. We are debating the organization of content that does not exist yet. Instead of shipping two empty tabs, we should ship one clean tab that is inviting enough for someone to actually use. **Kenya Hara:** The empty state is the most important state. When a user opens the vault and sees two empty tabs -- "Knowledge" and "Skills" -- they feel twice as empty. They have to understand the distinction before they can even begin. One tab with a clear empty state -- "Add documents, guides, and workflows to your agent's knowledge base" -- is immediately actionable. **Mem0 perspective:** Merging reduces the API surface too. Instead of `fetchDocuments()` and `fetchSkills()`, you have one function that fetches files from a knowledge directory. The skill-specific metadata (parameters, steps, trigger) is parsed from frontmatter on files that have it. Fewer endpoints, fewer types, fewer bugs. **Verdict:** Strong case for merging. Simpler mental model, better empty state, less API surface, matches how users naturally organize information. --- ### Round 4: The case for keeping them separate **Letta perspective:** The strongest argument for separation is *UI affordances*. Skills have a genuinely different display: parameter tables, step lists, usage statistics, trigger configuration. Documents have a different display: rich text viewer, version history, folder browsing. If we merge them, we need smart detection to show the right UI for each file. That is more engineering complexity hidden behind apparent simplicity. **Kenya Hara:** There is also the authorship argument. Knowledge documents are typically uploaded or written by the human owner. Skills could be *learned* by the agent -- extracted from repeated patterns in conversations. The creation flow might differ: upload/write for knowledge, auto-generate for skills. Separate sections could support separate creation flows. **Steve Jobs:** Those are implementation concerns, not user concerns. The viewer can adapt based on content type. A markdown file with frontmatter gets a skill renderer. A plain markdown file gets a document renderer. The user does not need to pre-categorize -- the system detects and adapts. And for authorship: whether a file was uploaded by a human or generated by an agent is metadata, not a reason for a separate tab. **Allen Zhang:** I will play devil's advocate on one point. Skills have *execution semantics* that documents do not. A skill can be "triggered" -- the agent runs it as a procedure. Documents are passive reference material. If we ever build a "run this skill" button, that functionality makes no sense on a regular document. But -- we are not building that today. And if we do build it, it can be a button that appears only on files with skill frontmatter. **Verdict:** The arguments for separation are real but addressable. Smart rendering handles display differences. Metadata handles authorship. Conditional UI handles execution semantics. None of these require a separate tab. --- ### Round 5: What if we merge but with smart display? **Steve Jobs:** This is the design. One "Knowledge" tab. Folder browser as the primary view, exactly like the current implementation. Files are files. But when you open a file that has structured skill frontmatter -- YAML with `name`, `parameters`, `steps`, `trigger` -- the viewer switches to the SkillDetail renderer automatically. The file shows up in the folder browser like any other file, but with a lightning bolt icon instead of a document icon. No categorization needed from the user. **Kenya Hara:** The visual language should make the difference *felt* without being *explained*. In the folder browser: document files get a blue file icon, skill-formatted files get a green lightning bolt. The user sees the difference at a glance but never has to choose. The system detected it from the content. **Allen Zhang:** For the folder structure in the repo, we keep a single `knowledge/` directory. Users can create any subfolder structure they want. If they want a `knowledge/skills/` subfolder, they can have one. If they want `knowledge/engineering/runbooks/`, they can do that too. The folder structure is the user's organizational choice, not our imposed taxonomy. **Letta perspective:** For agent retrieval, we can add a `type` field to the file metadata. Files with skill frontmatter get `type: skill`. Others get `type: document`. The agent's retrieval system can use this to route queries -- "How do I do X?" searches skills first, "What is X?" searches documents first. The optimization exists in the backend without polluting the UI. **Mem0 perspective:** This is exactly the right pattern. Store uniformly, display smartly, retrieve intelligently. The user sees one clean interface. The agent gets optimized retrieval. The developer maintains one data path. **Verdict:** Merge with smart display. One tab, one folder structure, automatic detection, adaptive rendering. --- ### Round 6: Jobs makes the call **Steve Jobs:** Let me make this concrete with three questions. **What ships faster?** One tab. We already have the FolderBrowser and DocumentViewer components. We already have the SkillDetail and SkillCard components. We delete the "Skills" tab, move the skill rendering logic into the Knowledge tab, and add file-type detection. We *remove* code rather than adding it. The tab definition goes from five entries to four. The `Skill` type becomes a display variant, not a separate data model. **What serves users better?** One tab. A new user opens their vault. They see four tabs: Overview, Memories, Conversations, Knowledge. Each tab has a clear, distinct purpose. Knowledge is "all the reference material and workflows your agent can access." No confusion about where to put things. No empty Skills tab staring at them. **What creates less confusion?** One tab. The current design forces users to answer a philosophical question before they can store a file: "Is this knowledge or a skill?" That question has no clean answer for most content. Removing the question removes the friction. The call: **Merge. Ship four tabs. Knowledge absorbs Skills.** --- ### Round 7: What should the unified Knowledge tab look like? **Kenya Hara:** The layout stays almost identical to the current Knowledge tab. A folder browser. Breadcrumb navigation. Files listed with icons, names, modification dates. The changes are subtle: 1. **File icons are type-aware.** Document files (`.md`, `.txt`, `.pdf`) show a blue file icon. Files detected as skills (via frontmatter parsing) show a green lightning bolt. The user sees the difference without being told. 2. **Skill files in the list show a brief summary.** Instead of just filename and date, a skill file shows: name (from frontmatter), step count, parameter count. Like a richer list row. This is the current SkillCard information, condensed into a list item. 3. **Opening a skill file shows SkillDetail.** When you click a skill-formatted file, you get the SkillDetail renderer (parameters table, steps list, usage stats). When you click a regular document, you get the DocumentViewer. The viewer adapts to the content. 4. **Empty state is unified.** "Your knowledge base is empty. Add documents, guides, and workflows to give your agent reference material." One message. One call to action. **Allen Zhang:** The folder structure suggestion for new vaults: ``` knowledge/ guides/ -- reference docs, style guides, etc. workflows/ -- step-by-step procedures (skill-formatted files go here naturally) reference/ -- factual reference material ``` But this is a *suggestion*, not a requirement. Users can organize however they want. The system does not enforce categories. **Steve Jobs:** One more thing. On the Overview tab, the right sidebar currently has a "Skills" section showing the top 3 skills. Replace that with "Recent Knowledge" or just merge it into the "Recent Documents" section. If a file is a skill, it shows with its lightning bolt icon in the same list. No separate section needed. --- ### Round 8: Final naming and structure **Kenya Hara:** Naming options: - **"Knowledge"** -- clear, matches the domain (knowledge management). Slightly formal. - **"Files"** -- accurate but generic. Does not convey purpose. - **"Library"** -- warm, inviting, implies curated collection. Slightly metaphorical. - **"Docs"** -- too narrow, implies only documents, not workflows. **Steve Jobs:** "Knowledge." It is what it is. An agent's knowledge base. Not files, not a library, not docs. Knowledge. It matches our domain language. It matches the directory name. It matches user expectations. Ship it. **Allen Zhang:** Agreed. "Knowledge" is the right word. And the tab count drops from 5 to 4: ``` Overview | Memories | Conversations | Knowledge ``` Four tabs. Each with a distinct purpose. No overlap. No confusion. **Final structure:** The `Skill` TypeScript interface stays in the codebase -- it describes a display variant, not a storage category. The `Document` interface remains the primary type. When a Document's content contains skill frontmatter, the UI creates a `Skill` view from it. The transformation happens at render time, not at storage time. The repo directory structure becomes: ``` knowledge/ -- all files: documents, guides, workflows, skills *.md -- rendered as documents by default *.md (with YAML) -- auto-detected and rendered as skills ``` The `skills/` directory is deprecated. Existing files in `skills/` are shown in the Knowledge tab under a "skills" subfolder for backward compatibility. --- ## Recommendation ### 1. Decision: Merge Knowledge and Skills merge into a single "Knowledge" tab. A skill is a knowledge file with structured frontmatter, not a separate concept. **Rationale:** - Both are files in a Git repo, fetched and read identically by the agent - The separation forces users to answer an unanswerable categorization question - Real-world data shows both directories are empty -- we are designing for zero adoption - Four tabs (Overview, Memories, Conversations, Knowledge) are cleaner than five - Matches how users organize in Notion, Google Drive, and wikis: by topic, not by type ### 2. Unified Knowledge tab design - **Primary view:** FolderBrowser (unchanged) - **File type detection:** Parse frontmatter on `.md` files. If file contains `parameters:` and `steps:` sections, treat as skill - **Visual differentiation:** Skill files get a green lightning bolt icon; document files get a blue file icon - **Adaptive viewer:** Clicking a skill-formatted file opens SkillDetail; clicking a document opens DocumentViewer - **Unified empty state:** "Your knowledge base is empty. Add documents, guides, and workflows for your agent." - **Overview tab:** Merge "Skills" sidebar section into "Recent Documents" section, with type-aware icons ### 3. Naming - Tab name: **Knowledge** - Repo directory: `knowledge/` - Internal types: `Document` (primary), `Skill` (display variant parsed from Document content) - The `skills/` directory is supported for backward compatibility but not promoted in the UI ### 4. Implementation impact **Remove:** - `skills` entry from the `Tab` type union (line 24 of vault page) - "Skills" tab button and tab content section - "Skills" sidebar section on Overview tab - Separate `fetchSkills()` API call (absorb into `fetchDocuments()`) - `useSkills()` hook (absorb into `useDocuments()`) **Modify:** - `fetchDocuments()` -- also scan `skills/` directory, merge results into document list - FolderBrowser -- add icon type detection (lightning bolt for skill files vs file icon for documents) - Document click handler -- detect skill frontmatter and route to SkillDetail vs DocumentViewer - Overview tab -- merge recent skills into recent documents list - `Vault` type -- replace `skillCount` with a computed value or remove - `SharedSpace` type -- replace `skillCount` similarly **Keep unchanged:** - `Skill` interface -- still used for rendering SkillDetail - `SkillDetail` component -- still used as the viewer for skill-formatted files - `SkillCard` component -- can be reused as a list row variant in FolderBrowser - `fileToSkill()` transform -- still used, but called from the document pipeline when frontmatter is detected - `parseSkillContent()` -- still used for frontmatter detection **New:** - `isSkillFile(content: string): boolean` -- utility to detect skill frontmatter in a document - Type-aware icon rendering in FolderBrowser (check if document has skill frontmatter) ### 5. Migration path 1. Modify `fetchDocuments()` to also scan `skills/` directory 2. Add `isSkillFile()` detection utility 3. Update FolderBrowser to show type-aware icons 4. Update document click handler to route to SkillDetail when appropriate 5. Remove "Skills" tab from tab bar 6. Merge Overview tab sidebar sections 7. Update Vault and SharedSpace types/transforms This is additive-then-subtractive: the Knowledge tab gains skill rendering before the Skills tab is removed. No functionality is lost.