Skip to main content
The Relevance AI agent skills repository is a local reference that teaches your AI coding assistant how to work with Relevance AI. Clone it once and your assistant gets detailed context on agents, tools, workforces, knowledge, analytics, and evals — without needing to figure things out from scratch.
Agent skills work alongside the MCP server. The MCP server gives your assistant the ability to call Relevance AI tools. Agent skills give it the knowledge to use them well.

​
Quick start

1

Clone the agent skills repository

Choose the path that matches your AI coding assistant:
git clone https://github.com/RelevanceAI/agent-skills ~/.claude/skills/relevance-ai
2

Connect the MCP server

The agent skills provide context, but your assistant still needs the MCP server to actually interact with your Relevance AI project. Follow the setup for your client on the MCP Server page.
3

Verify the connection

Ask your AI assistant to list your agents or tools:
> List all my Relevance AI agents
If the assistant returns your agents, you’re all set.

​
What’s included

The agent skills repository contains structured reference documentation that your AI assistant reads on-demand:

SKILL.md

The main skill definition — covers all 46 MCP tools, critical usage rules, and workflow patterns your assistant should follow.

Reference docs

Detailed guides for agents, tools, workforces, knowledge, analytics, and evals that the assistant reads when working on specific tasks.

​
Creating skills programmatically

While you can manually create and edit SKILL.md files in the agent skills repository, you can also create and manage skills programmatically using the Skills API. This is useful for automation workflows, CI/CD pipelines, or any scenario where you need to generate or update skills without manual editing.

​
Structured fields

The Skills API accepts four structured fields when creating or updating a skill:
A unique identifier for the skill. Must be lowercase with hyphens, maximum 64 characters.Example: pdf-processing
A comprehensive description of what the skill does. This is used to help AI agents understand the skill’s purpose and capabilities. Maximum 1024 characters.Example: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs
Activation hints that help AI agents determine when to use this skill. These hints appear in the skills catalog for trusted skills and provide specific guidance on the contexts or scenarios where the skill should be activated.Unlike description (which explains what the skill does), when_to_use tells the agent when to reach for it. This distinction matters because an agent might recognize a skill is relevant to PDFs but not know whether to activate it for a general document question versus a specific PDF task.Example: Use when the user mentions PDFs, asks to extract data from documents, needs to fill forms, or wants to combine multiple files
The full Markdown content of the skill instructions. This is equivalent to the body of SKILL.md — include tool descriptions, usage patterns, critical rules, and any context the AI assistant needs to use the skill correctly.

​
Trusted skills

Trusted skills are verified skills that appear in the skills catalog with enhanced visibility. When a skill is marked as trusted, the when_to_use field is displayed prominently to help AI agents decide whether to activate it for a given task. If you are building skills intended for catalog distribution, populate when_to_use with specific, scenario-based hints rather than generic descriptions.

​
Code example

import requests

API_URL = "https://api.relevanceai.com/v1/skills"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

skill = {
    "name": "pdf-processing",
    "description": "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs",
    "when_to_use": "Use when the user mentions PDFs, asks to extract data from documents, needs to fill forms, or wants to combine multiple files",
    "content": """# PDF processing

## Overview
Use these tools to work with PDF files in Relevance AI.

## Tools
- `pdf_extract_text` — extracts plain text from a PDF file
- `pdf_extract_tables` — returns structured table data from a PDF
- `pdf_fill_form` — fills a PDF form given a field map
- `pdf_merge` — combines multiple PDFs into one

## Usage rules
- Always check the file size before extracting — files over 50 MB may time out
- Use `pdf_extract_tables` instead of `pdf_extract_text` when the user needs structured data
- `pdf_fill_form` requires the exact field names from the PDF; fetch them with `pdf_get_form_fields` first
""",
}

response = requests.post(API_URL, json=skill, headers=headers)
response.raise_for_status()
print(response.json())

​
Topics covered

Agents

Creating agents, system prompts, actions, memory, triggers, and troubleshooting.

Tools

Building tools, transformations, OAuth configuration, versioning, and patterns.

Workforces

Multi-agent orchestration concepts, setup, and debugging.

Knowledge

Knowledge table operations — creating tables, adding rows, querying data.

Analytics

Usage metrics and reporting capabilities.

Evals

Testing agent behaviour with evaluation cases.

​
Keeping skills up to date

The agent skills repository is a standard Git repo. Pull the latest changes periodically: 
cd ~/.agents/skills/relevance-ai  # or ~/.claude/skills/relevance-ai
git pull

​
How it works

When your AI assistant encounters a Relevance AI task, it reads the relevant files from the agent skills repository to understand:
  • Which MCP tools to call — the skill definition maps tasks to specific tool names
  • What parameters to use — reference docs include required fields and correct formats
  • What pitfalls to avoid — critical rules like “always fetch full agent config before updating” prevent common mistakes
This means your assistant can handle complex workflows (like creating an agent with tools, triggers, and a system prompt) correctly on the first try, rather than through trial and error.
Agent skills follow the Agent Skills open standard. Any AI coding assistant that supports this convention can use them.