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.

Start here

Graph-of-Skills is an MCP server. In plain words: a small online service that your AI coding agent, such as Claude Code, can ask for help. You give your agent a task. It asks Graph-of-Skills which written method (a skill) fits that task, and gets the text back. You do not install a skill yourself. You connect the service once, in four steps.

MCP: (Model Context Protocol): a standard way for an agent to call outside tools.
Agent: (also called an MCP client or AI coding assistant): the AI coding program you give tasks to, for example Claude Code, Cursor or VS Code with GitHub Copilot.
Skill: : a short written method for one kind of task, such as how to build a Word file.
Environment variable: : a named setting a program reads when it starts. Yours is called GOS_API_KEY and holds your key.
Plugin: : an add-on you install into Claude Code with one command.
Rules file: : a short file in your project that tells the agent when to ask for a skill.

The names you will see

What	Name
The product	Graph-of-Skills
The MCP server	`graph-of-skills`
The Claude Code plugin	`graph-of-skills@akilima`
The rules file	`.claude/rules/graph-of-skills.md`
The optional lookup skill	`graph-of-skills-lookup`
The four tools your agent can call	`search_skills`, `retrieve_skill_bundle`, `hydrate_skills`, `create_skill`

Before step 1: get an AI coding agent. Skip this if you already use Claude Code, Cursor or another agent that can use MCP servers.

Get a free key. No card.
Set the key in your terminal, then open a new terminal.
Connect your agent: the plugin, then the rules file. These are the recommended steps for Claude Code.
Check that it works.

Once it is connected, your agent 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.

Before step 1: get an AI coding agent

Graph-of-Skills does not write code or answer questions itself. It helps an AI coding agent that does. So you need an agent first: a program you give tasks to, such as Claude Code, Cursor or VS Code with GitHub Copilot. Another name for it is an MCP client.

You do not run a model on your computer. The agent sends your task to a hosted model over the internet. You need an account for the agent, not a powerful computer. For Claude Code, Anthropic's setup page says: "Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free claude.ai plan does not include Claude Code access."

Set up Claude Code

Get an account that includes Claude Code (see the quote above and Anthropic's setup page).
Open a terminal. If you have never used one, Anthropic has a terminal guide.
Paste the install command for your system and press Enter. It shows no progress while it downloads.
macOS, Linux and WSL
```
curl -fsSL https://claude.ai/install.sh | bash
```
Windows PowerShell
```
irm https://claude.ai/install.ps1 | iex
```
Windows Command Prompt
```
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
Open a new terminal window and run claude --version. A working install prints a version number.
Run claude and follow the browser prompts to sign in. When it opens, you are ready for step 1.

These commands are copied from Anthropic's page on 2026-10-15. If they differ from the page, follow the page. Anthropic also offers a desktop app that does not need a terminal; our steps below use the terminal.

Using another agent

Cursor: how Cursor adds MCP servers.
VS Code with GitHub Copilot: add and manage MCP servers in VS Code.
Other agents that can use MCP servers have their own setup pages. Use "Any other MCP client" in step 3.

The steps on this page, and every measurement on this site, are for Claude Code. Other agents should work through "Any other MCP client", but we have not tested them.

Step 1: Get a free key

The key tells the service who is asking. Create one on the sign-up page. No card is needed. You can see your key again later in your account.

Get my free API key

Step 2: Set your key

The order matters. Set the key, then open a new terminal window, then start your agent from that window. An agent that was already running does not see a new key. If you skip this, step 4 shows "Failed to connect".

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.

Step 3: Connect your agent

Recommended for Claude Code: two steps

Do the first, then the second. Everything below these two is an alternative, not a next step.

1 Install the Claude Code plugin

The connection, the lookup skill, create-skill, which drafts a missing skill with the create_skill tool for you to confirm, and install-own-skill, which saves a skill from your own library on this machine and is told to ask you first, 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 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, and to offer to write one when nothing fits. 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

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"

Other ways to connect

Pick one only if the recommended path does not fit: Claude Code by hand, a lookup skill, or another MCP client such as Cursor.

Connect Claude Code by hand, without the plugin

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}"
  }
}'

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. The command finds the skill because this site publishes a skills index at /.well-known/agent-skills/index.json.

terminal

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

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

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"

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.

Step 4: Check that it works

1. List your connections

In the same terminal where you set the key, run:

terminal

claude mcp list

A working setup prints a line for graph-of-skills that ends in "Connected":

expected output

graph-of-skills: https://www.akilima.tech/api/graph-of-skills/mcp (HTTP) - ✔ Connected

2. If it says "Failed to connect"

A line ending in "Failed to connect" with "HTTP 401" means the service did not receive your key. The key is not set in this terminal. Go back to step 2, set it, open a new terminal and run the command again.

3. Ask your agent to use it

Start Claude Code from that terminal and type:

Claude Code

Use Graph-of-Skills to find a skill for writing a Word document.

You should see Claude Code call a tool named retrieve_skill_bundle (it may ask your permission the first time; allow it), then name or use a skill it found. Inside Claude Code, /mcp also lists the server and its tools. If something else happens, see Troubleshooting.

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.

Let your agent write a skill

When no skill covers your task, your agent can draft one for your own library with the create_skill tool. A draft joins your library only when you confirm it.

The agent sends what you need. The server looks for a similar skill in your library and in the public catalogue. If it finds one, the agent shows it to you and uses it. It drafts a new skill only if you ask for one anyway.
If nothing is similar, the agent writes the skill. It is told to show you the whole draft in your terminal and wait for your yes before it saves it. The server cannot see your terminal, so step 4 is the check that holds.
The server checks the format and the size (up to 20,000 characters). It refuses a draft that holds hidden characters or an encoded payload. It also refuses a step that sends a credential to a web address and a step that downloads and runs a script. Other lines it flags are saved with the draft and shown to you. The check looks for known patterns and misses some, so read the draft yourself.
The saved draft is pending and not searchable. Open the link in the agent's reply, or the Skills waiting for your review card in your dashboard, read the draft and press Confirm. An API key cannot confirm, so your agent cannot do it for you. A draft you leave alone expires after 7 days and can no longer be confirmed.

After you confirm, the skill is in your own library. It is not shared with other accounts, and results mark it as created by your agent. You can hold up to 20 pending drafts at a time.

The tool works without any extra file. To give your agent the short instructions for when to offer it, install the skill: npx skills add https://www.akilima.tech --skill create-skill -g -a claude-code -y

Install one of your skills on a machine

Your agent finds your skills through the server. You can also save one as a file on a machine, so Claude Code lists it with no lookup. There are two ways.

With the button

Open your dashboard. Each skill in the "Your skill library" card has an Install on this machine button.
Press it. The page shows a command and a Copy button.
Run the command in a terminal on the machine that should have the skill. It uses npx skills add to save the skill in ~/.claude/skills, so every project on that machine can use it.

The link inside the command works for 10 minutes. It works like a password while it lasts, so anyone who holds it can download that one skill. Do not share it. If a skill has no button, this site has install links turned off. Use your agent instead.

With your agent

Ask your agent to keep one of your skills on this machine. With the plugin installed, the install-own-skill skill tells it to fetch the file with hydrate_skills. It is told to show you the whole file and wait for your yes. It also asks whether to save the skill for this project or for all of them. Without the plugin, the description of hydrate_skills gives a connected agent the same instruction.

Your agent cannot make a link for you, because an API key cannot ask for one. Only your signed-in dashboard can.

What you get

Both ways save a SKILL.md built from the text we store. Its layout can differ from the file you uploaded. Scripts and other files the skill came with are not included. A skill from the public catalogue has its own npx skills add command on its page in the catalogue.

For developers: the button calls POST /api/graph-of-skills/install-link with your sign-in, not a key. The command downloads GET /api/graph-of-skills/install/{token}. Both are in the OpenAPI file.

How skills are sourced and what we check

Where skills come from

The public catalogue lists skills that skills.sh publishes. They come from GitHub repositories and other public sites. New skills are added once they have at least 1,000 installs. Some older entries have fewer.

What you get back

A lookup returns a skill as its author published it. We do not edit it. Each catalogue result names where it came from, and the response carries a notice that you are responsible for how you use it.

What we do not check

We do not scan skill content for harmful instructions. The one exception is a draft that your agent writes with create_skill. The server looks for known risky patterns in that draft and refuses it if it finds a serious one. It misses some. It does not read catalogue skills, files you upload or the text we return. A skill is text that your agent reads, and an agent can follow instructions in text it reads. Treat every skill as untrusted. Read a skill before your agent acts on it. Take most care when it asks the agent to run commands, read your files or send data out.

What still protects you

Your agent's permission prompts still decide what it can run. In Claude Code, the agent asks before it runs a command or edits a file, unless you have allowed that ahead of time. Keep the prompts on when you try a skill you do not know.

Report a skill

Write to legal@akilima.tech or use the contact page. Name the skill and say what is wrong. If a report holds up, we hide the skill, so it stops coming back in results.

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), `create_skill` (checks for a similar skill, then holds a draft for you to confirm in your dashboard).
`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

Start here

The names you will see

Before step 1: get an AI coding agent

Set up Claude Code

Using another agent

Step 1: Get a free key

Step 2: Set your key

macOS (zsh)

Linux (bash)

Windows (PowerShell)

Windows (Command Prompt)

Step 3: Connect your agent

Recommended for Claude Code: two steps

1 Install the Claude Code plugin

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

Or the same on Windows

Other ways to connect

Connect Claude Code by hand, without the plugin

Add the lookup skill

Or download the skill file (macOS and Linux)

Or download the skill file (Windows)

Any other MCP client

Step 4: Check that it works

1. List your connections

2. If it says "Failed to connect"

3. Ask your agent to use it

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

Let your agent write a skill

Install one of your skills on a machine

With the button

With your agent

What you get

How skills are sourced and what we check

Where skills come from

What you get back

What we do not check

What still protects you

Report a skill

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