> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skilldiscs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LLM Agent Integration

> Wire SkillDiscs into Claude, GPT, or any tool-using agent.

SkillDiscs exposes REST endpoints that map cleanly onto LLM tool definitions. This guide shows the minimal tool surface for retrieval-augmented agents.

## Recommended tool surface

Three tools cover \~95% of agent use cases:

1. **`search_knowledge`** → `POST /api/v1/search`
2. **`read_disk`** → `GET /api/v1/disks/{id}`
3. **`list_disks`** → `GET /api/v1/disks?scope=…&category=…&tag=…` (browsing)

Skip `batch` unless you measure round-trip latency as a bottleneck.

## Anthropic / Claude tool definition

```json theme={null}
{
  "name": "search_knowledge",
  "description": "Search the user's personal knowledge base (their imported articles, videos, PDFs) by natural-language query. Returns the most relevant section excerpts.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Natural-language search query" },
      "limit": { "type": "integer", "default": 5, "maximum": 25 }
    },
    "required": ["query"]
  }
}
```

In your tool handler, forward to:

```javascript theme={null}
const r = await fetch('https://skilldiscs.com/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SKILLDISCS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(input),
})
return await r.json()
```

When building context for the model, use `section_text` when present and fall back to `snippet`:

```javascript theme={null}
const { results } = await r.json()
const context = results.map(hit => ({
  title: hit.disk_title,
  text: hit.section_text ?? hit.snippet,
  key_points: hit.key_points ?? [],
  redacted: hit.redacted,
}))
```

## OpenAI / GPT function calling

Same JSON Schema, register under `tools` with `type: "function"`. Forward to the same endpoint.

## Prompt template

```
You have access to the user's personal knowledge base via three tools:
- search_knowledge(query, limit) — semantic search across owned Disks
- read_disk(id) — metadata, key points, and conditional text for one Disk
- list_disks(scope?, category?, tag?) — browse the library

Always cite the Disk title when referencing retrieved content.
Prefer search_knowledge over read_disk unless the user names a specific Disk.
If a result is redacted, treat snippet/key_points as context and do not imply access to the full source.
```

## Gotchas

* **Never embed the API key in a client-side bundle.** Always proxy through your backend.
* Search is **per-user and owned-Disk scoped** in current production.
* Check `redacted`. Full source text is only returned for owner-private Disks.
* Embeddings are computed at import time; newly imported Disks are searchable within seconds.