# Research Report: Claude Code Skills System & Agent Knowledge Patterns

**Date:** 2026-03-19
**Purpose:** Inform KnowHub's Knowledge and Skills design with evidence from Claude Code's skill system and the broader agent knowledge ecosystem.

---

## Part 1: Claude Code Skills — Anatomy, Structure, and Lifecycle

### 1.1 What Is a Skill?

A skill is a directory containing a `SKILL.md` file with YAML frontmatter and Markdown instructions that extends what Claude Code can do. Skills are the primary extension mechanism: Claude loads them automatically when relevant to the conversation, or the user invokes them directly via `/skill-name`. Skills follow the [Agent Skills open standard](https://agentskills.io/specification), now adopted by 26+ platforms including OpenAI Codex, Gemini CLI, GitHub Copilot, Cursor, and VS Code.

The official documentation states: "Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit."

Source: [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills)

### 1.2 Directory Structure

Each skill is a directory with `SKILL.md` as the required entrypoint:

```
my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
├── references/
│   └── REFERENCE.md   # Detailed technical reference
├── scripts/
│   └── validate.sh    # Script Claude can execute
└── assets/
    └── schema.json    # Static resources (templates, data files)
```

The Agent Skills specification defines three optional standard directories:
- **`scripts/`** — Executable code that agents can run (Python, Bash, JavaScript)
- **`references/`** — Additional documentation agents read on demand
- **`assets/`** — Static resources: templates, images, data files, lookup tables

Source: [Agent Skills Specification](https://agentskills.io/specification)

### 1.3 SKILL.md File Format

Every `SKILL.md` has two parts:

**YAML frontmatter** (between `---` markers) — metadata that controls discovery and invocation:

| Field | Required | Purpose |
|-------|----------|---------|
| `name` | No (defaults to directory name) | Display name and `/slash-command`. Lowercase letters, numbers, hyphens. Max 64 chars. |
| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to auto-load. Max 1024 chars. |
| `disable-model-invocation` | No | `true` prevents Claude from auto-triggering (user-only invocation). |
| `user-invocable` | No | `false` hides from `/` menu (agent-only background knowledge). |
| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. |
| `context` | No | `fork` runs in a separate subagent context. |
| `agent` | No | Which subagent type (e.g., `Explore`, `Plan`) when `context: fork`. |
| `model` | No | Model override when this skill is active. |
| `argument-hint` | No | Hint shown during autocomplete (e.g., `[issue-number]`). |
| `hooks` | No | Lifecycle hooks scoped to this skill. |
| `license` | No | License name or reference (Agent Skills standard field). |
| `compatibility` | No | Environment requirements (Agent Skills standard field). |
| `metadata` | No | Arbitrary key-value pairs for additional properties. |

**Markdown body** — the actual instructions Claude follows. Recommended sections: step-by-step instructions, examples of inputs/outputs, common edge cases.

Source: [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills), [Agent Skills Specification](https://agentskills.io/specification)

### 1.4 Example: Real Skills from Local System

Two real skills exist on this machine at `~/.claude/skills/`:

**`issue-solving-loop`** — An orchestration skill that drives a PR through a dev pipeline until merge. It dispatches to dev agents, runs quality-gate reviews, loops on failure, and tracks block counts. It uses `$ARGUMENTS` for repo and issue number, spawns background agents, polls session logs, and interacts with GitHub and Telegram APIs. This is 120 lines of procedural instructions with bash command templates.

**`pipeline-triage`** — A scanning/analysis skill that examines all open issues and PRs across repos, classifies their pipeline stage (20+ possible states), prioritizes tasks across agent roles, and dispatches task lists via Telegram. It is nearly 300 lines of structured decision logic with classification tables and output templates.

Both follow the pattern: frontmatter with `name` and `description`, then detailed step-by-step procedures with embedded code blocks. Neither uses `context: fork` or `allowed-tools` — they run inline in the main conversation.

### 1.5 How Skills Are Triggered and Invoked

Skills follow a three-tier context loading model (progressive disclosure):

1. **Metadata** (~100 tokens): The `name` and `description` of all available skills are loaded at session startup so Claude knows what exists.
2. **Instructions** (< 5000 tokens recommended): The full `SKILL.md` body loads only when the skill is activated.
3. **Resources** (as needed): Supporting files (`scripts/`, `references/`, `assets/`) load only when Claude reads them during execution.

Invocation paths:

| Method | How it works |
|--------|-------------|
| **User invokes directly** | Type `/skill-name [args]` in the conversation |
| **Claude auto-invokes** | Claude reads the skill descriptions in context and decides to load one when relevant |
| **Subagent preloads** | A subagent definition can list skills to inject at startup |

The `disable-model-invocation` and `user-invocable` fields create a 2x2 control matrix:

| Setting | User can invoke | Claude can invoke | Description in context |
|---------|----------------|-------------------|----------------------|
| (default) | Yes | Yes | Yes |
| `disable-model-invocation: true` | Yes | No | No |
| `user-invocable: false` | No | Yes | Yes |

Source: [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills)

### 1.6 Where Skills Live — Scope and Precedence

| Location | Path | Scope |
|----------|------|-------|
| Enterprise | Managed settings | All users in the organization |
| Personal | `~/.claude/skills/<name>/SKILL.md` | All projects for this user |
| Project | `.claude/skills/<name>/SKILL.md` | This project only |
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Wherever the plugin is enabled |
| Nested (monorepo) | `packages/frontend/.claude/skills/` | Auto-discovered when working in that subdirectory |

Precedence: enterprise > personal > project. Plugin skills use a `plugin-name:skill-name` namespace and cannot conflict.

### 1.7 How Skills Compose

Skills compose through several mechanisms:

1. **Claude's reasoning** — Claude can apply multiple skills to a single task. There is no explicit skill-to-skill linking; composition happens through Claude deciding which skills are relevant.

2. **Subagent delegation** — A skill with `context: fork` runs in an isolated subagent. The main conversation delegates a task, the subagent executes using the skill's instructions, and results return to the parent.

3. **Tiered architecture** — `CLAUDE.md` provides always-on project context. Skills layer specialized capabilities on top. Subagents operate in isolated contexts for research-heavy or parallel work.

4. **Dynamic context injection** — The `!`command`` syntax runs shell commands before skill content reaches Claude. Output replaces the placeholder, enabling live data (e.g., `!`gh pr diff``) to be injected.

5. **String substitutions** — `$ARGUMENTS`, `$ARGUMENTS[N]`, `$N`, `${CLAUDE_SESSION_ID}`, `${CLAUDE_SKILL_DIR}` enable parameterized skills.

6. **Bundled skills as orchestrators** — Built-in skills like `/batch` decompose work into units and spawn one background agent per unit in isolated git worktrees.

Source: [Claude Code Skills Docs](https://code.claude.com/docs/en/skills), [Claude Code Customization Guide](https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/)

### 1.8 The Agent Skills Open Standard

In December 2025, Anthropic released the Agent Skills specification as an open standard at [agentskills.io](https://agentskills.io). The specification defines the minimal portable format:

- `name` and `description` are required fields
- Directory must contain `SKILL.md` at minimum
- Name must match the parent directory name
- Lowercase alphanumeric + hyphens only, max 64 chars
- `license`, `compatibility`, and `metadata` are optional
- `allowed-tools` is experimental

Claude Code extends the base standard with additional fields: `disable-model-invocation`, `user-invocable`, `context`, `agent`, `model`, `hooks`, and `argument-hint`.

Microsoft, OpenAI, Atlassian, Figma, Cursor, and GitHub have adopted the standard. The `skills-ref` validation library at [github.com/agentskills/agentskills](https://github.com/agentskills/agentskills) can validate skill directories.

Source: [Agent Skills Specification](https://agentskills.io/specification), [Anthropic Opens Agent Skills Standard — Unite.AI](https://www.unite.ai/anthropic-opens-agent-skills-standard-continuing-its-pattern-of-building-industry-infrastructure/)

### 1.9 Skills Architecture Best Practice: Separation of Concerns

The recommended architecture separates **process** from **context**:

- **Process** (in `SKILL.md`): Ordered steps Claude should follow. Target 40-100 lines. Four components: skill description, prerequisites/inputs, process steps, output specification.
- **Context** (in reference files): Background information, rules, domain knowledge, examples, and reference data.

Every step involving evaluation or judgment must reference a specific file defining the criteria. Steps should explicitly load reference files: "Load `reference/tone-guidelines.md` and review against every guideline."

Reference files don't auto-load. The process must instruct Claude which files to read and when, enabling conditional loading based on context.

Source: [Claude Code Skills Architecture — MindStudio](https://www.mindstudio.ai/blog/claude-code-skills-architecture-skill-md-reference-files)

---

## Part 2: How Skills Differ from Plain Documents

### 2.1 The Fundamental Distinction

A document is passive reference material — it answers "what is X?" A skill is an action-oriented specification — it answers "how do I do X?" But this distinction is a spectrum, not a binary:

| Dimension | Document | Skill |
|-----------|----------|-------|
| **Purpose** | Inform | Instruct |
| **Structure** | Free-form prose | Frontmatter + procedural steps |
| **Invocation** | Searched/retrieved on demand | Explicitly triggered or auto-matched |
| **Context loading** | Loaded when agent searches | Description always in context; body loads on activation |
| **Tool access** | None | `allowed-tools` grants permissions |
| **Execution** | Read-only | Can spawn subagents, run scripts, inject dynamic data |
| **Arguments** | N/A | Accepts `$ARGUMENTS` |
| **Composition** | Standalone | Composes via subagent delegation and orchestration |
| **Lifecycle** | Static (human-maintained) | Active (can have hooks, validators, continuation paths) |

### 2.2 The Spectrum in Practice

As KnowHub's own design discussion concluded: "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." The real-world examples from this machine's `~/.claude/skills/` confirm this — both the `issue-solving-loop` and `pipeline-triage` skills are essentially elaborate documents with structured frontmatter that happen to be procedural.

### 2.3 Why the Distinction Still Matters Architecturally

Even if the user-facing concept merges (as KnowHub decided), the architectural distinction matters for three reasons:

1. **Progressive disclosure** — Skill descriptions (100 tokens) are loaded at session startup for matching. Document content is only retrieved on demand. This is a fundamentally different context-loading strategy.

2. **Execution semantics** — Skills can grant tool permissions, run in isolated contexts, accept arguments, inject dynamic data, and spawn subagents. Documents cannot.

3. **Retrieval routing** — As the Letta/MemGPT perspective notes: "Procedural memory is invoked when the agent needs to *do* something. Archival memory is searched when the agent needs to *know* something." The retrieval patterns differ even when storage is unified.

---

## Part 3: Knowledge Organization Patterns for Agents

### 3.1 From RAG to Knowledge Infrastructure

The industry is evolving from simple document retrieval (RAG) toward structured knowledge infrastructure for agents. The key insight from the research paper "Knowledge Activation" (arXiv:2603.14805):

> "Knowledge artifacts designed for human consumption — narrative documentation, lengthy runbooks, sprawling wiki pages — are systematically misaligned with the requirements of agent consumption, wasting tokens on rhetorical scaffolding and omitting the structured metadata that agents require."

Source: [Knowledge Activation: AI Skills as the Institutional Knowledge Primitive — arXiv](https://arxiv.org/html/2603.14805v1)

### 3.2 Six Agentic Knowledge Base Patterns

Research from The New Stack identifies six patterns emerging in production:

1. **Curated skill libraries** — Pre-structured procedural knowledge in standardized formats (the Agent Skills pattern)
2. **Semantic knowledge graphs** — Entities, relationships, and traversal paths rather than flat documents
3. **Hybrid retrieval** — Combining vector search, keyword search, and graph traversal
4. **Progressive disclosure** — Metadata first, summaries second, full content on demand
5. **Institutional memory** — Past interactions, decisions, and outcomes as searchable context
6. **Governance-embedded knowledge** — Permissions, compliance annotations, and audit trails intrinsic to the knowledge artifact

LinkedIn implemented an agentic knowledge base and reported a 20% increase in AI coding adoption and ~70% reduction in issue triage time.

Source: [6 Agentic Knowledge Base Patterns — The New Stack](https://thenewstack.io/agentic-knowledge-base-patterns/)

### 3.3 Knowledge Activation vs. Retrieval-Augmented Generation

The Knowledge Activation paper formalizes a critical distinction:

| Dimension | RAG | Knowledge Activation |
|-----------|-----|---------------------|
| Delivery unit | Unstructured text passages | Pre-structured specifications |
| Content burden | Agent interprets, infers tools | Ready-to-execute with embedded governance |
| Optimization target | Semantic relevance | Actionable information per token (knowledge density) |
| Governance | Absent from retrieval | Intrinsic to artifact design |
| Maintenance model | Update documents | Version-controlled knowledge commons |

The key metric is **knowledge density** (rho): actionable information per token consumed. A typical 2,000-token enterprise runbook can be compressed to a 300-token Atomic Knowledge Unit (AKU) delivering equivalent capability — 6-7x greater density. This is not summarization but purposeful restructuring for agent consumption.

Source: [Knowledge Activation — arXiv:2603.14805](https://arxiv.org/html/2603.14805v1)

### 3.4 The Atomic Knowledge Unit (AKU)

The paper defines AKUs as the fundamental knowledge primitive for agents, bundling seven components:

1. **Intent Declaration** — what the skill accomplishes
2. **Procedural Knowledge** — step-by-step guidance
3. **Tool Bindings** — explicit service integrations
4. **Organizational Metadata** — ownership and service catalog references
5. **Governance Constraints** — permissions and compliance annotations
6. **Continuation Paths** — relationships to other skills
7. **Validators** — deterministic scripts verifying organizational standards

This maps directly to the Agent Skills standard: `description` (intent), markdown body (procedural knowledge), `allowed-tools` (tool bindings), `metadata` (organizational), permission rules (governance), and `scripts/` (validators).

Source: [Knowledge Activation — arXiv:2603.14805](https://arxiv.org/html/2603.14805v1)

### 3.5 Multi-Modal Knowledge Representation

Best practices from 2026 recommend five representation layers:

1. **Unstructured** — Raw documents, transcripts, PDFs, emails
2. **Semantic** — Embeddings and similarity search
3. **Structured** — Entities, taxonomies, attributes, metadata
4. **Relational/Graph** — Dependencies, ownership, hierarchies, workflows
5. **Temporal** — Versioning, validity windows, historical state

Hybrid retrieval (vector + keyword + metadata facets + optional re-ranking) is the default recommendation. GraphRAG — combining vector search with structured ontologies — is emerging as the approach for when relationships between knowledge items matter.

Source: [RAG Playbook — Regal AI](https://www.regal.ai/blog/rag-playbook-structuring-knowledge-bases), [Graph RAG & LLMs — OneReach](https://onereach.ai/blog/graph-rag-the-future-of-knowledge-management-software/)

### 3.6 How Leading Platforms Handle Knowledge

**OpenAI Assistants/Responses API**: Uses file_search with vector stores. Automatically chunks documents, creates embeddings, runs hybrid keyword+semantic search, and re-ranks results. The Assistants API was deprecated in January 2026 (shutdown August 2026), replaced by the Responses API + Conversations API. Knowledge is stored as files in vector stores — a document-centric, RAG-based approach.

Source: [OpenAI Assistants File Search](https://platform.openai.com/docs/assistants/tools/file-search), [Assistants API Deprecation Guide](https://ragwalla.com/docs/guides/openai-assistants-api-deprecation-2026-migration-guide-wire-compatible-alternatives)

**Glean**: Enterprise search across 100+ connectors (Jira, Confluence, Google Drive). Uses a Knowledge Graph to connect and structure information. RAG-based retrieval parses data on request without training on it. Centralized cross-platform indexing layer.

**Notion AI**: Ecosystem-native search with AI Agents that maintain contextual memory. "Custom Instructions" encode workspace preferences, brand voice, and team structure. Enterprise Search surfaces results from Slack, GitHub, and Google Drive within Notion. Knowledge is workspace-embedded, not a separate system.

Source: [Glean AI Review — CyberNews](https://cybernews.com/ai-tools/glean-ai-review/), [How Notion AI Is Changing Work — Medium](https://metafluxtech.medium.com/how-notion-ai-is-changing-the-way-we-work-in-2026-729cc6ad79d3)

**KPMG Knowledge Engineering**: Advocates three pillars — semantic layer (translates structures into business language), ontology (defines domain concepts), and knowledge graph (enables relationship traversal). The argument: "We are at the end of the 'big data' era and at the dawn of the 'big knowledge' era."

Source: [Why Knowledge Engineering Is Key to AI Agent Value — KPMG](https://kpmg.com/us/en/articles/2026/why-knowledge-engineering-is-the-key-to-ai-agent-value.html)

### 3.7 What Makes Knowledge Agent-Consumable

Synthesizing across all sources, agent-consumable knowledge has these properties:

1. **Single-topic chunks** — Each unit addresses one topic or question. "Smaller, well-scoped chunks ensure that when a retrieval occurs, the AI gets just the specific information it needs."

2. **Concrete instructions** — Imperative language ("Call Submit to save") rather than hedged language ("you may want to consider").

3. **Explicit outcome statements** — Desired end-states within each chunk ("Outcome: Appointment is canceled and confirmation email is sent").

4. **Contextual labels** — Front-loaded scope: "Return Policy (California customers)" not just "Return Policy".

5. **Consistent terminology** — No jargon agents may misinterpret. "Do not XYZ" rather than "XYZ is not recommended".

6. **Structured metadata** — Tags, types, relationships, ownership, validity periods.

7. **Explicit relationships** — "Our SLA applies to enterprise customers, except during maintenance windows, unless escalated by account managers" rather than "Our SLA is 24 hours."

8. **Progressive disclosure** — Metadata (always loaded) -> summary (loaded on match) -> full content (loaded on activation) -> supporting files (loaded on demand).

Source: [RAG Playbook — Regal AI](https://www.regal.ai/blog/rag-playbook-structuring-knowledge-bases), [Anatomy of an AI Agent Knowledge Base — InfoWorld](https://www.infoworld.com/article/4091400/anatomy-of-an-ai-agent-knowledge-base.html)

---

## Part 4: Agent-First vs. Human-First Knowledge

### 4.1 The Core Difference

| Property | Human-First | Agent-First |
|----------|-------------|-------------|
| **Optimization** | Readability, narrative flow | Token efficiency, knowledge density |
| **Structure** | Prose paragraphs, sections | Frontmatter + structured fields + procedural steps |
| **Rhetorical scaffolding** | Expected (introductions, transitions, conclusions) | Wasteful (consumes tokens without adding information) |
| **Ambiguity** | Tolerated (humans infer from context) | Costly (agents hallucinate to fill gaps) |
| **Relationships** | Implied (hyperlinks, cross-references) | Explicit (continuation paths, dependency declarations) |
| **Governance** | Separate documents (policy manuals, access control lists) | Embedded (permissions, constraints, validators in the artifact) |
| **Retrieval** | Browsing, search, table of contents | Semantic matching, type-based routing, progressive disclosure |
| **Freshness** | Periodic review cycles | Continuous validation, version control, staleness detection |
| **Completeness** | Assumed (reader fills gaps from experience) | Required (agent has no unstated institutional knowledge) |

### 4.2 Context Rot

The Knowledge Activation paper introduces "context rot" — what happens when agents work without pre-structured institutional knowledge:

> "Agents guess at procedures, violate unstated constraints, receive corrections, retry — accumulating context tokens with detritus rather than actionable information. This progressively degrades reasoning capability even as model context windows expand."

This creates an "institutional knowledge tax" where senior engineers absorb disproportionate overhead correcting agent errors. Despite 90% AI tool adoption, developers report that finding institutional information remains a leading productivity drain.

Source: [Knowledge Activation — arXiv:2603.14805](https://arxiv.org/html/2603.14805v1)

### 4.3 The Knowledge Density Imperative

Agent-first knowledge maximizes the ratio of actionable information to tokens consumed. Techniques:

- **Eliminate rhetorical scaffolding** — Remove introductions, transitions, and conclusions that exist for human reading flow
- **Foreground actionable content** — Lead with what to do, not background
- **Embed metadata** — Structured frontmatter rather than scattered prose mentions
- **Use decision tables** — Replace paragraphs of conditional logic with lookup tables
- **Explicit tool references** — Name the tools, APIs, and commands; don't describe them abstractly
- **Conditional loading** — Reference files load only when relevant, not upfront

### 4.4 Dual-Audience Design

The pragmatic approach is **dual-audience design**: knowledge that serves both humans and agents. This means:

- Markdown with structured frontmatter (human-readable format with machine-parseable metadata)
- Clear headings and bullet points (good for both scanning and retrieval)
- Explicit rather than implicit relationships (helps both audiences)
- Progressive disclosure (humans skim; agents load selectively)
- Version control (Git works for both audiences)

The Agent Skills standard achieves this: `SKILL.md` is a Markdown file (human-readable) with YAML frontmatter (machine-parseable). A human can read it in any text editor. An agent can parse the frontmatter, load it selectively, and execute it.

---

## Part 5: Recommendations for KnowHub's Knowledge and Skills Design

### 5.1 Validate the Merge Decision

KnowHub's decision to merge Knowledge and Skills into a single "Knowledge" tab is well-supported by the research. The arguments:

- **The Agent Skills standard itself** is just a Markdown file with frontmatter — it is a document with execution semantics, not a fundamentally different artifact.
- **User mental models** organize by topic/domain, not by declarative-vs-procedural type.
- **Storage is identical** — both are files in Git.
- **The agent treats them the same** at the I/O level (reads a file).

The research confirms one nuance: the **architectural distinction** between passive reference and active procedure still matters internally, even when the user-facing concept is unified. KnowHub should detect skill-formatted files (via frontmatter) and route them through different retrieval and display paths.

### 5.2 Adopt the Agent Skills Standard

KnowHub should adopt the [Agent Skills open standard](https://agentskills.io/specification) as the format for procedural knowledge files. Reasons:

1. **Interoperability** — Files are compatible with Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot, Cursor, VS Code, and 20+ other platforms.
2. **Validation tooling** — The `skills-ref` library validates skill structure.
3. **Progressive disclosure** — The metadata/instructions/resources model is built into the standard.
4. **Extensibility** — Claude Code's extended fields (`context`, `agent`, `hooks`) show how platforms add capabilities without breaking the base format.

For KnowHub, this means: files in the `knowledge/` directory that have valid Agent Skills frontmatter (`name`, `description`) are treated as skills for display and retrieval purposes. Files without frontmatter are treated as documents. The detection is content-based, not location-based.

### 5.3 Implement Progressive Disclosure in Retrieval

KnowHub's retrieval system should mirror Claude Code's three-tier model:

| Tier | What loads | When | Token cost |
|------|-----------|------|------------|
| 1. Index | Name + description of all knowledge items | Session startup / agent initialization | ~100 tokens per item |
| 2. Content | Full body of the matched item | When the agent (or user) activates it | < 5000 tokens recommended |
| 3. Resources | Supporting files, scripts, references | When the agent explicitly reads them | Variable |

This means KnowHub needs to store and serve descriptions separately from full content, enabling agents to browse a knowledge catalog without loading everything.

### 5.4 Design for Knowledge Density

Every knowledge item in KnowHub should optimize for knowledge density — actionable information per token. Practical guidelines for KnowHub's authoring experience:

- **Provide templates** that encourage structured frontmatter (name, description, steps, parameters)
- **Show token count** as a quality signal during editing
- **Encourage chunking** — one topic per file, with explicit cross-references to related items
- **Support conditional loading** — allow skills to reference supporting files that load on demand
- **Detect and flag** rhetorical scaffolding (long introductions, hedged language, abstract descriptions)

### 5.5 Implement Dual Retrieval Routing

When an agent asks KnowHub for information, the system should route differently based on intent:

- **"How do I do X?"** — Search skills/procedural content first (match against `description` fields)
- **"What is X?"** — Search documents/reference content first (semantic search on full content)
- **"What happened with X?"** — Search memories/conversations first (temporal search)

This can be implemented as metadata-based routing on a unified store — no separate tabs required, but separate retrieval strategies per content type. The `type: skill` vs `type: document` metadata (detected from frontmatter) enables this.

### 5.6 Support Knowledge Topology

Beyond flat file storage, KnowHub should capture relationships between knowledge items:

- **Continuation paths** — "After completing this skill, the next step is usually [skill-name]"
- **Prerequisites** — "This skill requires understanding [document-name]"
- **Alternatives** — "For a different approach, see [skill-name]"
- **Composition** — "This meta-skill orchestrates [skill-a], [skill-b], and [skill-c]"

These relationships enable agents to navigate knowledge graphs rather than performing independent searches for each step. The Knowledge Activation paper calls these "agent-navigable knowledge topologies" — interconnected nodes that agents traverse at runtime.

### 5.7 Embed Governance in Knowledge Artifacts

Following the AKU model, KnowHub should support governance metadata within knowledge items:

- **Ownership** — Who maintains this item
- **Permissions** — Which agents/users can access it
- **Freshness** — Last verified date, review schedule
- **Validators** — Scripts or checks that verify the knowledge is still accurate
- **Compliance annotations** — Regulatory framework mappings where relevant

This is especially important because "freshness, or lack thereof, is the silent killer of AI knowledge systems." KnowHub should track when items were last validated and surface stale content.

Source: [Anatomy of an AI Agent Knowledge Base — InfoWorld](https://www.infoworld.com/article/4091400/anatomy-of-an-ai-agent-knowledge-base.html)

### 5.8 Consider Future Compatibility with Multi-Agent Systems

The local skills on this machine (`issue-solving-loop`, `pipeline-triage`) demonstrate a pattern: skills that orchestrate multiple agents across GitHub, Telegram, and custom agent platforms. KnowHub's knowledge system should anticipate:

- **Skills that reference external tools** (GitHub CLI, APIs, agent platforms)
- **Skills that spawn sub-tasks** across multiple agents
- **Knowledge that is shared across agent teams** (the `marketing-commons` shared space pattern already in KnowHub)
- **Skills with dynamic context** (injecting live data from APIs at invocation time)

### 5.9 Summary of Concrete Actions

| Priority | Action | Rationale |
|----------|--------|-----------|
| P0 | Detect skill frontmatter in knowledge files; render with SkillDetail when present | Unified store with smart display |
| P0 | Store description separately; serve as catalog for progressive disclosure | Agents need to browse without loading everything |
| P1 | Adopt Agent Skills frontmatter fields (name, description, allowed-tools, metadata) | Cross-platform compatibility |
| P1 | Implement dual retrieval routing (procedural vs reference intent) | Better agent accuracy |
| P2 | Add relationship metadata (continuation paths, prerequisites) | Enable knowledge topology navigation |
| P2 | Track freshness (last-verified date, review schedule) | Prevent knowledge rot |
| P3 | Support `scripts/` and `references/` subdirectories per knowledge item | Full Agent Skills standard support |
| P3 | Provide authoring templates with token-count feedback | Encourage knowledge density |

---

## Sources

### Claude Code Skills System
- [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills)
- [Agent Skills Specification](https://agentskills.io/specification)
- [Agent Skills GitHub — Anthropic](https://github.com/agentskills/agentskills)
- [Anthropic Opens Agent Skills Standard — Unite.AI](https://www.unite.ai/anthropic-opens-agent-skills-standard-continuing-its-pattern-of-building-industry-infrastructure/)
- [Claude Code Skills Architecture — MindStudio](https://www.mindstudio.ai/blog/claude-code-skills-architecture-skill-md-reference-files)
- [Claude Code Customization Guide — alexop.dev](https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/)
- [Claude Code Merges Slash Commands Into Skills — Medium](https://medium.com/@joe.njenga/claude-code-merges-slash-commands-into-skills-dont-miss-your-update-8296f3989697)
- [Claude Code Commands vs Skills — OneAway](https://oneaway.io/blog/claude-code-commands-vs-skills)
- [Essential Claude Code Skills and Commands — batsov.com](https://batsov.com/articles/2026/03/11/essential-claude-code-skills-and-commands/)
- [Awesome Claude Code — GitHub](https://github.com/hesreallyhim/awesome-claude-code)

### Agent Knowledge Patterns
- [Knowledge Activation: AI Skills as Institutional Knowledge Primitives — arXiv:2603.14805](https://arxiv.org/html/2603.14805v1)
- [6 Agentic Knowledge Base Patterns — The New Stack](https://thenewstack.io/agentic-knowledge-base-patterns/)
- [Anatomy of an AI Agent Knowledge Base — InfoWorld](https://www.infoworld.com/article/4091400/anatomy-of-an-ai-agent-knowledge-base.html)
- [Why Knowledge Engineering Is Key to AI Agent Value — KPMG](https://kpmg.com/us/en/articles/2026/why-knowledge-engineering-is-the-key-to-ai-agent-value.html)
- [RAG Playbook: Structuring Knowledge Bases — Regal AI](https://www.regal.ai/blog/rag-playbook-structuring-knowledge-bases)
- [From RAG to Knowledge Infrastructure for Agents — Medium](https://medium.com/@mrschneider/from-rag-chatbots-to-knowledge-infrastructure-for-agents-35926f147205)
- [Graph RAG & LLMs — OneReach](https://onereach.ai/blog/graph-rag-the-future-of-knowledge-management-software/)
- [RAG in 2026 — Squirro](https://squirro.com/squirro-blog/state-of-rag-genai)

### Platform-Specific Knowledge Approaches
- [OpenAI Assistants File Search](https://platform.openai.com/docs/assistants/tools/file-search)
- [Assistants API Deprecation Guide — Ragwalla](https://ragwalla.com/docs/guides/openai-assistants-api-deprecation-2026-migration-guide-wire-compatible-alternatives)
- [Glean AI Review — CyberNews](https://cybernews.com/ai-tools/glean-ai-review/)
- [How Notion AI Is Changing Work — Medium](https://metafluxtech.medium.com/how-notion-ai-is-changing-the-way-we-work-in-2026-729cc6ad79d3)
- [Agentic Coding Trends 2026 — Anthropic Report](https://resources.anthropic.com/hubfs/2026%20Agentic%20Coding%20Trends%20Report.pdf)