> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourhq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Knowledge and agent context
> Give agents shared knowledge and per-agent context using the unified knowledge system.
Knowledge items are how you give agents durable context — company background, style guides, SOPs, research, files, and standing rules — without repeating yourself every conversation. The knowledge system replaces the old documents and assets model with a single, unified library.
***
## How it works
Every knowledge item has a **kind** (what it is) and a **scope** (who can see it):
**Page** — rich-text documents (company briefs, style guides, priorities).
**Skill** — structured procedures and SOPs.
**File** — uploaded files (images, PDFs, spreadsheets, audio, video).
**Source** — externally synced content from connected integrations.
**Workspace** — visible to all agents in the workspace. Pin it to include in every agent's boot context.
**Agent** — visible only to specific agents, assigned via the agent junction.
***
## Giving agents boot context
Boot context is what an agent reads before doing any work. Two mechanisms control it:
| Mechanism | What it does |
| ---------------------------------- | --------------------------------------------------------------------------------------- |
| **Workspace scope + pinned** | A pinned workspace-scoped item is injected into **every agent's** startup context. |
| **Agent scope + agent assignment** | An agent-scoped item assigned to specific agents is injected only for **those agents**. |
Go to **Knowledge** in the left sidebar and create a new page, skill, or upload a file.
For **all agents**: set scope to **Workspace** and toggle **Pinned** on.
For **specific agents**: set scope to **Agent** and assign the agents who should receive it from the agent picker.
The next time an agent wakes up (via a message, a task, or a routine), it reads the item as part of its startup context. No restart required — changes take effect on the next session.
***
## Organizing knowledge
Use **folders** to organize items by topic. Folders support nesting and custom icons.
Use **tags** for cross-cutting labels (e.g. "q2-2026", "onboarding", "legal"). Tags are separate from scope — they're for your own organization, not for controlling agent access.
Use **pinned** to surface important workspace items in boot context without having to remember which folder they're in.
***
## Keeping knowledge effective
Large boot context slows agents down and reduces their effectiveness. Context has a limit — the more you pack in, the less room the agent has to think about the actual task.
**Keep each item focused.** One item per topic is better than one giant document with everything. An agent reads all items in its boot context, so you can have multiple short ones.
**Keep them current.** An agent reading stale knowledge ("Q1 priorities" in Q3) is worse than reading nothing — it acts on outdated information. Review pinned items quarterly or when your situation changes significantly.
**Signs knowledge is stale:**
* The agent references old project names or priorities
* It uses outdated context in responses
* It contradicts what you've told it recently in conversation
To update: edit the item directly — changes take effect on the next session.
***
## Good boot context examples
Who you are, what the company does, who the customers are, your stage, your voice. 3-5 paragraphs maximum. Every agent benefits from this context.
Tone, vocabulary, formatting preferences, what to avoid. Examples of good and bad outputs help more than abstract rules. Pin it workspace-wide if all agents should follow it, or scope it to specific writer agents.
What matters right now — 3-5 bullet points. Update at the start of each quarter. Helps agents prioritize when they have discretion.
Hard rules that should never be broken: "never commit to pricing", "always CC \[name] on outbound", "don't share confidential deal terms". Short list, no ambiguity.
Step-by-step workflows for recurring tasks — e.g., how to research a new contact, how to structure a newsletter draft, how to handle inbound inquiries. Role-specific, so assign to the relevant agents only.
***
## Agent-created skills
Agents don't just consume knowledge — they create it. When an agent discovers a reusable method during work, it can autonomously create a **skill** scoped to itself. This happens via the `hq_skill_upsert.py` skill.
**When agents create skills:**
* After performing the same sequence 3+ times successfully
* After a breakthrough discovery (figuring out a non-obvious method through trial and error)
* When the user gives a reusable instruction that isn't already documented
**What you see:**
* The agent detail page shows a **Skills** section with the agent's self-created procedures
* A blue dot indicates recent edits (within 7 days), with the one-line reason displayed below
* The knowledge editor's **History** panel shows who made each edit (agent name + emoji vs "You")
* The dashboard fleet card shows how many skills were updated this week
**No approval gate.** Agents write directly. You observe via the audit trail and can edit, refine, or delete skills at any time through the standard knowledge editor. If you correct a skill, the agent will respect your edits on subsequent sessions.
***
## Entity links
Knowledge items can be linked to tasks, routines, collection records, and agents using **entity links**. Links are bidirectional references — they show up on both the owner and the target.
When an agent claims a task, it receives all linked entities (knowledge items, contacts, organizations, collection records) as context for that task. This replaces the old task attachments system with a universal linking model.
You can also link external URLs. URL links show up alongside entity links but open in a new tab instead of navigating within HQ.