Graph-of-Skills docs

Graph-of-Skills finds the skill that already solves your agent's task and returns it with its full text. This page covers setup, what a lookup does, uploading your own skills, limits and the API. For what it is for and what it costs, see the overview. For a test of whether it helps an agent follow a team's own conventions, see the benchmark.

Quick start

Create a free API key. No card. Store it as GOS_API_KEY, as shown under Set your key.
Install the Claude Code plugin, or pick another option under Connect your agent.
Run the one-line rules file command under Connect your agent in each project. It tells your agent when to look a skill up.
Give your agent a task. It looks up a skill when the task involves a file format, tool or convention it may not know. You can also ask for it: add "look up a skill first" to your request.

Set your key

Every connection option below reads your key from an environment variable named GOS_API_KEY, so the key never sits in a config file. A program reads its environment once, when it starts. Set the key first, open a new terminal, then start your agent from that terminal. An agent that was already running does not see the new variable.

macOS (zsh)

Adds the key to your zsh profile. Open a new terminal, then start your agent from it.

terminal

echo 'export GOS_API_KEY=your_key_here' >> ~/.zshrc

Check it in the new window. Above 0 means it is set: echo ${#GOS_API_KEY}

Linux (bash)

Adds the key to your bash profile. Open a new terminal, then start your agent from it. On zsh, use ~/.zshrc instead.

terminal

echo 'export GOS_API_KEY=your_key_here' >> ~/.bashrc

Check it in the new window. Above 0 means it is set: echo ${#GOS_API_KEY}

Windows (PowerShell)

Stores the key for your Windows user. Open a new PowerShell window, then start your agent from it.

PowerShell

[Environment]::SetEnvironmentVariable("GOS_API_KEY", "your_key_here", "User")

Check it in the new window. Above 0 means it is set: $env:GOS_API_KEY.Length

Windows (Command Prompt)

Stores the key for your Windows user. Open a new Command Prompt, then start your agent from it.

cmd

setx GOS_API_KEY "your_key_here"

Check it in the new window. Above 0 means it is set: echo %GOS_API_KEY%

The export lines in the connect options below are for macOS and Linux. On Windows, set the key as above, then use the .mcp.json option, which holds the same ${GOS_API_KEY} placeholder.

Connect your agent

1 Install the Claude Code plugin

The connection and the lookup skill in one step. The key stays in your environment, so start Claude Code from a terminal where it is set.

terminal

export GOS_API_KEY=your_key_here
claude plugin marketplace add benman1/graph-of-skills-claude-plugin
claude plugin install graph-of-skills@akilima

2 Or connect Claude Code by hand

Two commands. The key stays in your environment, not in the config file.

terminal

export GOS_API_KEY=your_key_here
claude mcp add-json --scope user graph-of-skills '{
  "type": "http",
  "url": "https://www.akilima.tech/api/graph-of-skills/mcp",
  "headers": {
    "Authorization": "Bearer ${GOS_API_KEY}"
  }
}'

3 Tell your agent when to use it (macOS and Linux)

Run this once in each project. It saves a short rules file that Claude Code reads at the start of every session; it tells the agent to look a skill up before work on a file format, a named tool or your team's own conventions. Without it the agent looks things up less often.

terminal

curl -fsSL --create-dirs https://www.akilima.tech/downloads/graph-of-skills-rules.md -o .claude/rules/graph-of-skills.md

Download the rules file

4 Or the same on Windows

The same file, saved with PowerShell.

PowerShell

New-Item -ItemType Directory -Force -Path ".claude\rules" | Out-Null
Invoke-WebRequest https://www.akilima.tech/downloads/graph-of-skills-rules.md -OutFile ".claude\rules\graph-of-skills.md"

5 Add the lookup skill

One short skill that tells your agent to check for a written method before unfamiliar work. Without it, the agent calls the tools only when you ask.

terminal

npx skills add https://www.akilima.tech -g -a claude-code -y

6 Or download the skill file (macOS and Linux)

The same skill as a plain file. Save it into your skills folder, or open it first to read what it says.

terminal

mkdir -p ~/.claude/skills/graph-of-skills-lookup
curl -fsSL https://www.akilima.tech/downloads/graph-of-skills-lookup/SKILL.md -o ~/.claude/skills/graph-of-skills-lookup/SKILL.md

Download SKILL.md

7 Or download the skill file (Windows)

The same file, saved with PowerShell.

PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\graph-of-skills-lookup" | Out-Null
Invoke-WebRequest https://www.akilima.tech/downloads/graph-of-skills-lookup/SKILL.md -OutFile "$HOME\.claude\skills\graph-of-skills-lookup\SKILL.md"

8 Any other MCP client

Cursor, Claude Desktop and other clients that accept a remote HTTP server.

.mcp.json

{
  "mcpServers": {
    "graph-of-skills": {
      "type": "http",
      "url": "https://www.akilima.tech/api/graph-of-skills/mcp",
      "headers": {
        "Authorization": "Bearer ${GOS_API_KEY}"
      }
    }
  }
}

Your key is in your account. Every snippet reads it from GOS_API_KEY, so nothing here puts a key in a file.

What happens on a task

1

You give your agent a task

For example: convert the table on page 3 of this PDF to CSV.
2

The agent checks for a written method

The lookup skill tells it to search before work in an unfamiliar format, tool or convention. Without that skill, it searches when you ask.
3

It sends one sentence to Graph-of-Skills

The call is retrieve_skill_bundle over MCP, or a plain HTTP request. The sentence describes the task.
4

We search the public catalog and your own skills

The search matches exact words, such as an error code or a file extension, and matches meaning. It ranks the results.
5

You get the best matches, with their full text

The text is cut to fit a size limit you can set: 15,000 characters by default, up to 60,000.
6

The agent reads them and follows the one that fits

Nothing is installed on your machine. If no skill fits, the agent carries on as it would have.

About 6 in 10 skills in the public catalog list extra files next to SKILL.md: reference pages, scripts and templates. A result carries the SKILL.md text and a link to the source. A skill that needs its scripts on disk works best installed with npx skills add.

A real request and response

Shortened for the page. The live response carries each skill's full text.

request

curl -s -X POST https://www.akilima.tech/api/graph-of-skills/bundle \
  -H "Authorization: Bearer $GOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "convert a table in a PDF to a CSV file", "max_skills": 3}'

response

{
  "skills": [
    {
      "name": "pdf",
      "origin": "catalog",
      "installs": 197835,
      "content": "---\nname: pdf\ndescription: Use this skill whenever the user wants to do anything with PDF files..."
    },
    {
      "name": "xlsx",
      "origin": "catalog",
      "installs": 170276,
      "content": "---\nname: xlsx\ndescription: Use this skill any time a spreadsheet file is the primary input or output..."
    },
    {
      "name": "firecrawl-parse",
      "origin": "catalog",
      "installs": 50048,
      "content": "---\nname: firecrawl-parse\ndescription: Convert a local file (PDF, DOCX, XLSX, HTML) to markdown..."
    }
  ],
  "truncated": false
}

Searching well

Describe the task as an action and its object: "plan a client discovery call and scope the project" finds more than "consultancy conversations".
If nothing fits, search again with a narrower sentence for one stage of the work, such as discovery, scoping or status updates.
To read a skill, use retrieve_skill_bundle. search_skills lists names and short descriptions only.
You do not need to install a skill. The text comes back in the response and your agent uses it from there. Copy one into your own project only if you want it available without a call.

Your own skills

Add skills to your library from the dashboard (drag and drop), or upload SKILL.md files with a request:

terminal

curl -s -X POST https://www.akilima.tech/api/graph-of-skills/ingest \
  -H "Authorization: Bearer $GOS_API_KEY" \
  -F files=@my-skill.md

Send at most 5 files per request; a larger request gets a 413 and nothing is stored. Your library holds up to 200 skills. Your skills stay private to your key and are searched together with the public catalog, which you can browse.

Limits

Limit	Value
Skills per lookup (`max_skills`)	5 by default, up to 20
Result size (`max_chars`)	15,000 characters by default, up to 60,000
Files per upload request	5
Skills in your own library	200
Lookups per month, free plan	1,000
Requests per minute, free plan	120

Plans and prices are on the overview.

Troubleshooting

The server fails with 401, or Claude Code says "Missing environment variables: GOS_API_KEY"

Claude Code reads your key from its own environment when it starts. It was started from somewhere that never loaded your shell profile (an IDE, a desktop app, a launcher), or before you exported the key. A running program cannot pick up a new variable, so reconnecting from /mcp does not help.

In a terminal, check that the key is visible: the number below must be above 0. Then start Claude Code from that terminal. Use claude --continue to keep your conversation.

terminal

echo ${#GOS_API_KEY}

I start Claude Code from an app, not a terminal

Use a header helper instead. It is a short script that Claude Code runs each time it connects. It reads your key from the environment, or from the export line in ~/.zshrc, so the key stays in one place and this also works with /mcp reconnect. Replace the server you added earlier with the second command.

terminal

curl -fsSL https://www.akilima.tech/downloads/gos-headers.sh -o ~/.claude/gos-headers.sh
chmod +x ~/.claude/gos-headers.sh

terminal

claude mcp add-json --scope user graph-of-skills "{\"type\":\"http\",\"url\":\"https://www.akilima.tech/api/graph-of-skills/mcp\",\"headersHelper\":\"$HOME/.claude/gos-headers.sh\"}"

"Monthly retrieval free-tier cap reached" (429)

The free plan includes 1,000 retrievals a month, counted per account and reset at the start of each calendar month. Every call counts: test scripts, benchmarks and your agents share the same allowance. Pro raises it.

The same server is registered more than once

Claude Code connects only the highest-priority entry for a name: local, then project, then user. The others are ignored, so a duplicate does no harm, but it is easy to edit the wrong one. Remove extras with claude mcp remove graph-of-skills --scope project (or user, local).

API reference

Every call sends Authorization: Bearer $GOS_API_KEY. The full schema is in the OpenAPI file.

Where	What it does
`https://www.akilima.tech/api/graph-of-skills/mcp`	The MCP server. Tools: `search_skills` (names and short descriptions), `retrieve_skill_bundle` (matches with full text), `hydrate_skills` (full text for ids you already have).
`POST /api/graph-of-skills/retrieve`	Ranked matches for a task description.
`POST /api/graph-of-skills/bundle`	Matches with full text, sized to `maxChars`.
`POST /api/graph-of-skills/ingest`	Upload SKILL.md files to your library.
`GET /api/graph-of-skills/library`	List your skills and your usage against the limits.

      Source 
  
   
The Claude Code plugin and the lookup skill are open source under the
        MIT licence: graph-of-skills-claude-plugin on GitHub,
        with its own docs page.
        To report a problem with the service, use the contact page.
 
  
 
      Get my free API key  Back to the overview

Graph-of-Skills docs

Quick start

Set your key

macOS (zsh)

Linux (bash)

Windows (PowerShell)

Windows (Command Prompt)

Connect your agent

1 Install the Claude Code plugin

2 Or connect Claude Code by hand

3 Tell your agent when to use it (macOS and Linux)

4 Or the same on Windows

5 Add the lookup skill

6 Or download the skill file (macOS and Linux)

7 Or download the skill file (Windows)

8 Any other MCP client

What happens on a task

You give your agent a task

The agent checks for a written method

It sends one sentence to Graph-of-Skills

We search the public catalog and your own skills

You get the best matches, with their full text

The agent reads them and follows the one that fits

A real request and response

Searching well

Your own skills

Limits

Troubleshooting

The server fails with 401, or Claude Code says "Missing environment variables: GOS_API_KEY"

I start Claude Code from an app, not a terminal

"Monthly retrieval free-tier cap reached" (429)

The same server is registered more than once

API reference

Source