Skip to main content
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.

GitHub Repository

View the source code, installation instructions, and skill definitions.

​
What’s Included

The plugin bundles three skills and an MCP server configuration:

graphor-workflow

Core skill — teaches the agent the ingest → poll build status → query workflow using MCP tools. Auto-activates when relevant.

graphor-ts-sdk

TypeScript SDK patterns — activates when writing TypeScript/JavaScript code with the graphor npm package.

graphor-py-sdk

Python SDK patterns — activates when writing Python code with the graphor PyPI package.

.mcp.json

MCP Server config — auto-configures the graphor-mcp server for direct API access.

​
How It Works

The plugin follows the 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.
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.

​
Installation

The quickest way to install: 
/plugin marketplace add synapseops/graphor-skills
/plugin install graphor@graphor-skills
Set your API key when prompted: 
export GRAPHOR_API_KEY="grlm_your_api_key_here"
Add the export to your ~/.bashrc, ~/.zshrc, or equivalent so it persists across sessions.

​
Project-Level Installation (Team-Wide)

Copy the skills into your project’s .claude/skills/ directory so the entire team benefits: 
cp -r plugin/skills/* your-project/.claude/skills/

​
Personal Installation (All Projects)

Copy the skills to your personal Claude directory: 
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.
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.
Included rules:
RuleDescription
upload-sourcesIngest files, URLs, GitHub repos, or YouTube videos (returns build_id; poll for file_id)
parsingPoll build status and reprocess documents
ask-sourcesAsk questions about documents with conversational Q&A
extractionExtract structured data using JSON Schema
retrieve-chunksRetrieve chunks for custom RAG pipelines
manage-sourcesList 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: 
export GRAPHOR_API_KEY="grlm_your_api_key_here"
The bundled .mcp.json uses ${GRAPHOR_API_KEY} expansion to read this value automatically.
If MCP operations return authentication errors, the key is not set correctly. Run export GRAPHOR_API_KEY="grlm_..." and restart your agent tool.
Learn how to create and manage API tokens in the API Tokens guide.

​
Example Usage

Once installed, just talk to your agent naturally:
You say: “Ingest 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
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
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
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

​
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

Causes: GRAPHOR_API_KEY environment variable not set or incorrectSolutions:
  • 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_
Causes: Node.js not installed, npx not available, or plugin not installed correctlySolutions:
  • 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
Causes: The MCP server sandbox cannot access local filesSolutions:
  • 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
Causes: Skills not installed or not activatedSolutions:
  • 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

​
Next Steps

MCP Server

Learn more about the Graphor MCP Server that powers the skills

SDK Overview

Explore the full SDK documentation for Python and TypeScript

Ingest Sources

Detailed guide on ingesting documents, URLs, GitHub repos, and videos

Data Extraction

Extract structured data from documents with JSON Schema