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

# Agent Skills

> Give AI coding agents deep Graphor expertise with the Graphor Skills plugin for Claude Code and 27+ agent tools

**Graphor Skills** is a plugin that gives AI coding agents — such as Claude Code, Cursor, VS Code, GitHub Copilot, Gemini CLI, and more — deep domain expertise for working with Graphor. It bundles **MCP server connectivity** and **SDK coding knowledge** so your agent can ingest documents, poll build status, and query sources through natural language.

<Card title="GitHub Repository" icon="github" href="https://github.com/synapseops/graphor-skills">
  View the source code, installation instructions, and skill definitions.
</Card>

## What's Included

The plugin bundles three skills and an MCP server configuration:

<CardGroup cols={2}>
  <Card title="graphor-workflow" icon="diagram-project">
    **Core skill** — teaches the agent the ingest → poll build status → query workflow using MCP tools. Auto-activates when relevant.
  </Card>

  <Card title="graphor-ts-sdk" icon="js">
    **TypeScript SDK patterns** — activates when writing TypeScript/JavaScript code with the `graphor` npm package.
  </Card>

  <Card title="graphor-py-sdk" icon="python">
    **Python SDK patterns** — activates when writing Python code with the `graphor` PyPI package.
  </Card>

  <Card title=".mcp.json" icon="plug">
    **MCP Server config** — auto-configures the `graphor-mcp` server for direct API access.
  </Card>
</CardGroup>

## How It Works

The plugin follows the [Agent Skills](https://github.com/anthropics/agent-skills) open standard. When installed, the skills provide your agent with:

1. **Contextual knowledge** — The agent learns Graphor's core workflow (ingest, poll build status, query), API patterns, and best practices automatically.
2. **MCP server access** — The bundled `.mcp.json` configuration connects the agent to the Graphor MCP Server, giving it direct access to the API.
3. **SDK coding assistance** — When writing code that uses the Graphor SDK, the agent gets language-specific patterns, method signatures, error handling, and type safety guidance.

<Note>
  Skills activate automatically based on context — you don't need to explicitly load them. The workflow skill activates when you mention Graphor documents, and the SDK skills activate when writing code that imports `graphor`.
</Note>

## Installation

### Claude Code — Plugin Marketplace (Recommended)

The quickest way to install:

```bash theme={null}
/plugin marketplace add synapseops/graphor-skills
/plugin install graphor@graphor-skills
```

Set your API key when prompted:

```bash theme={null}
export GRAPHOR_API_KEY="grlm_your_api_key_here"
```

<Warning>
  Add the export to your `~/.bashrc`, `~/.zshrc`, or equivalent so it persists across sessions.
</Warning>

### Project-Level Installation (Team-Wide)

Copy the skills into your project's `.claude/skills/` directory so the entire team benefits:

```bash theme={null}
cp -r plugin/skills/* your-project/.claude/skills/
```

### Personal Installation (All Projects)

Copy the skills to your personal Claude directory:

```bash theme={null}
cp -r plugin/skills/* ~/.claude/skills/
```

### Other Agent Tools

Since the skills follow the Agent Skills open standard, they are portable across **27+ agent tools** including:

* Claude Code
* Cursor
* VS Code
* GitHub Copilot
* Gemini CLI
* And more

Consult your agent tool's documentation for how to install Agent Skills plugins.

## Skills Reference

### graphor-workflow

The primary skill. It teaches the agent the complete Graphor workflow and activates automatically when you mention document operations.

**Activation**: Auto-activates when the agent detects tasks related to ingesting, polling build status, or querying documents in Graphor.

**Core workflow**:

```
Ingest → Poll get_build_status → Query
```

The skill enforces the async workflow:

1. **Ingest** a source (file, URL, GitHub, YouTube) via MCP — returns **build\_id** immediately.
2. **Poll get\_build\_status(build\_id)** until **success** is true — status may be `Pending` (request received), then `Processing`, then `Completed`. Use the returned **file\_id** for all subsequent operations.
3. **Query** the source (ask, extract, retrieve\_chunks, get\_elements) or manage (list\_sources, delete\_source) using **file\_id**.

Optional: **Reprocess** an existing source with a different partition method — returns **build\_id**; poll get\_build\_status again.

<Warning>
  Ingest and reprocess are **asynchronous**. Always poll **get\_build\_status** until **success** is true before using **file\_id** for ask, extract, retrieve\_chunks, or get\_elements.
</Warning>

**Included rules**:

| Rule              | Description                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `upload-sources`  | Ingest files, URLs, GitHub repos, or YouTube videos (returns build\_id; poll for file\_id) |
| `parsing`         | Poll build status and reprocess documents                                                  |
| `ask-sources`     | Ask questions about documents with conversational Q\&A                                     |
| `extraction`      | Extract structured data using JSON Schema                                                  |
| `retrieve-chunks` | Retrieve relevant chunks via semantic search                                               |
| `manage-sources`  | List sources, get elements, or delete documents                                            |

**Universal rules the agent follows**:

1. Uses MCP tools for all operations (ingest\_file, ingest\_url, ingest\_github, ingest\_youtube, get\_build\_status, list\_sources, reprocess, get\_elements, delete\_source, ask, extract, retrieve\_chunks)
2. Uses **file\_id** from get\_build\_status (when success is true) or list\_sources — not from the ingest response (ingest returns build\_id only)
3. Polls get\_build\_status after ingest or reprocess until success is true
4. If auth errors occur, the `GRAPHOR_API_KEY` environment variable is not set correctly

### graphor-ts-sdk

Background knowledge skill for writing TypeScript/JavaScript code with the Graphor SDK.

**Activation**: Activates when writing TypeScript/JavaScript code that imports or uses the `graphor` npm package.

**Covers**:

* Client setup and initialization
* All SDK methods (`ingestFile`, `ingestURL`, `ingestGitHub`, `ingestYoutube`, `getBuildStatus`, `reprocess`, `list`, `delete`, `getElements`, `ask`, `extract`, `retrieveChunks`)
* Async ingest workflow (build\_id → poll getBuildStatus → file\_id)
* File upload patterns (`fs.createReadStream`, `toFile` helper)
* Error handling (`Graphor.BadRequestError`, `Graphor.NotFoundError`, etc.)
* Type safety and TypeScript interfaces

### graphor-py-sdk

Background knowledge skill for writing Python code with the Graphor SDK.

**Activation**: Activates when writing Python code that imports or uses the `graphor` PyPI package.

**Covers**:

* Sync (`Graphor`) and async (`AsyncGraphor`) clients
* All SDK methods (`ingest_file`, `ingest_url`, `ingest_github`, `ingest_youtube`, `get_build_status`, `reprocess`, `list`, `delete`, `get_elements`, `ask`, `extract`, `retrieve_chunks`)
* Async ingest workflow (build\_id → poll get\_build\_status → file\_id)
* File upload patterns (path, bytes, file-like objects)
* Error handling (`graphor.BadRequestError`, `graphor.NotFoundError`, etc.)
* Configuration (retries, timeouts, aiohttp)

## Authentication

All skills require a valid Graphor API key. Set it as an environment variable:

```bash theme={null}
export GRAPHOR_API_KEY="grlm_your_api_key_here"
```

The bundled `.mcp.json` uses `${GRAPHOR_API_KEY}` expansion to read this value automatically.

<Note>
  If MCP operations return authentication errors, the key is not set correctly. Run `export GRAPHOR_API_KEY="grlm_..."` and restart your agent tool.
</Note>

<Note>
  Learn how to create and manage API tokens in the [API Tokens guide](/guides/api-tokens).
</Note>

## Example Usage

Once installed, just talk to your agent naturally:

<AccordionGroup>
  <Accordion icon="arrow-up-from-bracket" title="Ingest and summarize a document">
    **You say**: *"Ingest [https://example.com/report](https://example.com/report) into Graphor and summarize it"*

    **Agent will**:

    1. Ingest the URL via MCP (ingest\_url) → receives build\_id
    2. Poll get\_build\_status until success → obtains file\_id
    3. Ask the document for a summary using file\_id
  </Accordion>

  <Accordion icon="table" title="Extract structured data">
    **You say**: *"Extract all invoice numbers and amounts from invoice.pdf in Graphor"*

    **Agent will**:

    1. Look up the file in your project (or ingest it and poll for file\_id)
    2. Use the extract MCP tool with a JSON Schema and file\_ids
    3. Return structured data
  </Accordion>

  <Accordion icon="code" title="Write SDK code">
    **You say**: *"Write a Python script that ingests all PDFs in a folder to Graphor and extracts their titles"*

    **Agent will**:

    1. Activate the `graphor-py-sdk` skill
    2. Write idiomatic Python using `ingest_file()`, `get_build_status()` (poll), then `extract()` with file\_id
    3. Include proper error handling and async polling until success
  </Accordion>

  <Accordion icon="magnifying-glass" title="Semantic search for relevant chunks">
    **You say**: *"Retrieve the most relevant chunks about payment terms from my contract"*

    **Agent will**:

    1. Use the retrieve\_chunks MCP tool (or SDK) with file\_ids
    2. Return chunks with file\_id, page numbers, and relevance scores
  </Accordion>
</AccordionGroup>

## Repository Structure

```
graphor-skills/
├── .claude-plugin/
│   └── marketplace.json           # Marketplace catalog
├── plugin/                        # The Graphor plugin
│   ├── .claude-plugin/
│   │   └── plugin.json            # Plugin metadata
│   ├── .mcp.json                  # MCP server config
│   └── skills/
│       ├── graphor-workflow/      # MCP workflow (hub + 6 rules)
│       │   ├── references/
│       │   ├── rules/
│       │   └── SKILL.md
│       ├── graphor-ts-sdk/        # TypeScript SDK patterns
│       └── graphor-py-sdk/        # Python SDK patterns
├── LICENSE
└── README.md
```

## Troubleshooting

<AccordionGroup>
  <Accordion icon="key" title="Authentication errors from MCP">
    **Causes**: `GRAPHOR_API_KEY` environment variable not set or incorrect

    **Solutions**:

    * Run `export GRAPHOR_API_KEY="grlm_your_api_key_here"` in your terminal
    * Add it to `~/.bashrc` or `~/.zshrc` for persistence
    * Restart your agent tool after setting the variable
    * Verify the key starts with `grlm_`
  </Accordion>

  <Accordion icon="plug" title="MCP server not connecting">
    **Causes**: Node.js not installed, npx not available, or plugin not installed correctly

    **Solutions**:

    * Verify Node.js 20+ is installed: `node --version`
    * Re-install the plugin: `/plugin install graphor@graphor-skills`
    * Check that `.mcp.json` exists in the plugin directory
    * Try running the MCP server manually: `npx -y graphor-mcp`
  </Accordion>

  <Accordion icon="file-circle-xmark" title="Local file uploads failing">
    **Causes**: The MCP server sandbox cannot access local files

    **Solutions**:

    * The workflow skill automatically uses `curl` via Bash for local file uploads
    * For URL, GitHub, and YouTube uploads, MCP tools work directly
    * Ensure your `GRAPHOR_API_KEY` is available in the shell environment
  </Accordion>

  <Accordion icon="robot" title="Agent not using Graphor skills">
    **Causes**: Skills not installed or not activated

    **Solutions**:

    * Verify installation: `/plugin list` should show `graphor`
    * Be explicit in your prompt: mention "Graphor" or "documents"
    * Check that skill files exist in `.claude/skills/` or the plugin directory
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Server" icon="server" href="/mcp-server">
    Learn more about the Graphor MCP Server that powers the skills
  </Card>

  <Card title="SDK Overview" icon="book" href="/sdk/overview">
    Explore the full SDK documentation for Python and TypeScript
  </Card>

  <Card title="Ingest Sources" icon="arrow-up-from-bracket" href="/sdk/sources/upload">
    Detailed guide on ingesting documents, URLs, GitHub repos, and videos
  </Card>

  <Card title="Data Extraction" icon="table" href="/sdk/extract">
    Extract structured data from documents with JSON Schema
  </Card>
</CardGroup>