Core Features

Agent Skills

Copy page

Agent Skills let you add new capabilities to Cortex Library's researcher agent. Skills are reusable instruction sets from the open AgentSkills ecosystem — install them from the skills.sh registry or any URL, run through a setup wizard, and the agent uses them automatically.

Overview

Enabled skills are automatically activated at the start of every research session. The agent sees their full instructions and can call external APIs using the built-in http_request tool. Authentication is handled entirely server-side — the LLM never sees tokens or API keys.

Skills work in both Deep Research and Chat modes. Agentic chat mode is enabled by default (ENABLE_AGENT_CHAT=true).

How It Works

1. You install a skill and run the Setup Wizard to provide any required credentials
2. You enable the skill from Settings
3. When a research or chat session starts, all enabled skills are loaded into the agent's context
4. The agent reads the skill instructions and calls APIs via http_request when relevant
5. Auth headers are built server-side from your saved configuration — the LLM only provides the HTTP method and URL

Installing Skills

From the Registry

1. Go to Settings > Agent Skills
2. Use the search bar under Browse Registry to find skills from skills.sh
3. Click Install on any result

From a URL

1. Go to Settings > Agent Skills
2. Paste a direct SKILL.md URL into the Install Skill field
3. Click Install

Local Skills

Place skill directories in your skills folder (default: .agents/skills/):

Code
 
.agents/skills/
  my-skill/
    SKILL.md          # Required — skill instructions

Click Discover to scan for new skills, or restart the application.

Setup Wizard

After installing a skill, it may show a "Needs setup" badge. Click Configure to open the Setup Wizard:

1. The primary LLM analyzes the SKILL.md to identify required configuration variables (API tokens, base URLs, etc.)
2. A modal presents each variable with a description and input field
3. Secret values (tokens, API keys) are masked and stored locally in a config.json file inside the skill directory
4. The configuration schema includes an auth_header template (e.g., Authorization: Bearer API_TOKEN) that tells the server how to build HTTP headers from your saved values

Once configured, the badge changes to reflect the skill is ready to use. You can reconfigure at any time from Settings.

Enabling Skills

Installed skills are disabled by default. Toggle them on from Settings > Agent Skills. Only enabled skills are loaded into the agent at session start.

The http_request Tool

When skills are active, the agent gains access to a built-in http_request tool for calling external APIs. The tool accepts:

Parameter	Required	Description
method	Yes	HTTP method: GET, POST, PUT, PATCH, DELETE
url	Yes	The full API URL to call
body	No	Optional request body for POST/PUT/PATCH

Server-side authentication: The server reads the auth_header templates from each skill's config schema, substitutes the stored credential values, and injects the resulting headers into the outgoing request. The LLM never handles tokens — it just specifies the method and URL from the skill's documentation.

Hostname-scoped auth: When multiple skills are installed, the server only applies a skill's auth headers if the request URL matches that skill's known hostname (derived from its base_url extracted automatically from SKILL.md, or from any URL-shaped config value like *_BASE_URL). This prevents two skills that both define Authorization headers from silently overwriting each other.

Failed calls are surfaced, never silent: If an API call fails — an error status (e.g. 401 Unauthorized, 403 Forbidden, 422 Unprocessable Entity) or a timeout — the failure is shown to you, not glossed over:

• A red skill step appears in the chat's research process with the failing method, URL, and HTTP status.
• The final answer explicitly tells you the action did not succeed and why (using the API's error message), rather than implying it worked.

This matters most for write actions (creating a ticket, opening a PR, posting data): a failed write will be reported as failed. Common causes are a missing/expired token (configure it in the skill's Setup Wizard), insufficient permissions on the token's account, or a request the target API rejects as invalid.

On-Demand Activation

In addition to auto-activation, the agent retains activate_skill and list_skills tools for activating additional skills mid-conversation. This is a fallback mechanism — in practice, all enabled skills are pre-loaded at session start.

Creating Skills

A skill is a directory containing a SKILL.md file with YAML frontmatter and instruction body:

Code
 
---
name: my-skill
description: What this skill does and when to use it.
license: Apache-2.0
metadata:
  author: your-name
  version: "1.0"
---

# My Skill

Instructions for the agent go here. Be specific about:
- When to use this skill
- What API endpoints are available
- What parameters each endpoint accepts
- What the response format looks like

## API Reference

### Search

GET https://api.example.com/search?q={query}

Returns a JSON array of results with title and url fields.

The agent reads these instructions and uses http_request to call the described endpoints. Write your SKILL.md as if you are explaining the API to a developer — the agent will follow the documentation to construct requests.

Configuration Schema

When a skill requires authentication, the Setup Wizard automatically detects the needed variables by analyzing the SKILL.md. The extracted schema is stored on the Neo4j Skill node and includes:

• name — Variable name (e.g., API_TOKEN)
• description — Where to find this value
• required — Whether the skill can function without it
• type — "secret" for tokens/passwords, "text" for URLs/identifiers
• auth_header — HTTP header template (e.g., Authorization: Bearer API_TOKEN)

Values are saved in config.json inside the skill directory. The auth_header template is used at runtime to build authentication headers server-side.

Configuration

Variable	Default	Description
ENABLE_SKILLS	true	Master switch for the skills system
SKILLS_DIR	.agents/skills	Skills directory path
ENABLE_AGENT_CHAT	true	Enable agentic chat mode (required for skills in Chat)
SKILL_HTTP_TIMEOUT	15	HTTP tool timeout in seconds
MAX_SKILL_TOOLS	10	Max skill tools in the agent
ENABLE_SKILL_SCRIPTS	false	Allow legacy script execution (security-sensitive)
SKILL_SCRIPT_TIMEOUT	30	Script timeout in seconds

Docker Volume Persistence

In Docker deployments, the skills directory is persisted via a named volume so installed skills survive container restarts:

Code
 
volumes:
  - skills_data:/app/.agents/skills

This is preconfigured in both docker-compose.prod.yml and the Coolify deployment file.

API Endpoints

All endpoints require Admin authentication.

Method	Endpoint	Description
GET	/api/admin/skills	List installed skills
GET	/api/admin/skills/{id}	Get full skill details (body + tools)
POST	/api/admin/skills/install	Install from URL or registry
PATCH	/api/admin/skills/{id}	Enable/disable a skill
DELETE	/api/admin/skills/{id}	Uninstall a skill
POST	/api/admin/skills/discover	Re-scan local skills directory
POST	/api/admin/skills/{id}/analyze	LLM-analyze SKILL.md for config variables
GET	/api/admin/skills/{id}/config	Get config schema + current values (secrets masked)
PUT	/api/admin/skills/{id}/config	Save config values (masked values preserve existing secrets)
GET	/api/admin/skills/registry/search?q=	Search skills.sh registry

Security

• The LLM never sees API tokens or credentials — authentication is injected server-side
• Only auth_header templates from the config schema are used to build HTTP headers
• Secret values in the config endpoint are masked (********) in API responses
• Config files are stored locally in the skill directory, not in the database
• Script execution is disabled by default (ENABLE_SKILL_SCRIPTS=false)
• All management endpoints require admin authentication
• Tool results are capped at 4000 characters
• Auth-related lines are stripped from skill instructions before injection to prevent the model from attempting manual authentication