Documentation

Serve a skill to an agent

FreeSkill stores portable Agent Skills packages, pins them into typed graphs, and hands an agent the smallest slice of context it needs. Everything below works against the live API. Public skills and trees need no token at all.

Quickstart

Every published tree is reachable over plain HTTP. Start with the catalog — it lists the skills in the tree and how they relate, without any instruction bodies.

cURL

curl https://api.freeskill.cloud/v1/trees/support-triage/catalog

For a private tree, add a scoped token created from Settings → Agent tokens:

cURL

curl https://api.freeskill.cloud/v1/trees/support-triage/catalog \
  -H "Authorization: Bearer $FS_TOKEN"

Progressive disclosure

Context is served in three widening steps, so an agent never loads a whole graph when it only needs one node.

/v1/trees/:tree/catalog	Node names, descriptions, and relationship hints. No instructions.
/v1/trees/:tree/plan	Topological layers, typed edges, control-node policies, failure policies.
/v1/trees/:tree/skills/:node	Activates one pinned revision and returns its instructions.
/v1/skills/:skill/revisions/:rev/files/*	Individual package resources for an activated revision.

Public responses are cached and carry an ETag. Private responses are always private, no-store.

Connect over MCP

The MCP adapter exposes the same tree, behind the same authorization boundary as REST. Point any MCP client at the tree endpoint.

mcp.json

{
  "mcpServers": {
    "support-triage": {
      "url": "https://api.freeskill.cloud/mcp/support-triage",
      "headers": { "Authorization": "Bearer $FS_TOKEN" }
    }
  }
}

Typed edges

Six edge types describe how skills relate at execution time. They are graph data, never written into SKILL.md, so a package stays portable.

requires	Target cannot run until this dependency is satisfied.
then	Runs sequentially after the source completes.
parallel	Runs concurrently with the source.
conditional	Runs only if a condition on the source is met.
fallback	Runs only if the source fails.
enhances	Optional context that improves, but is not required by, the target.

Command line

The CLI validates a package before you publish it and installs published skills into a local agent directory.

shell

freeskill login --token $FS_TOKEN
freeskill validate ./my-skill
freeskill push my-skill ./my-skill.zip
freeskill install support-triage --dir .agents/skills

What a package contains

A skill is an Agent Skills package: a SKILL.md with YAML frontmatter, plus any scripts, references, and assets it needs. Publishing a revision freezes it — editing creates a new revision with its own checksum and security scan. Public skills publish immediately; a revision is refused only if the scan finds something high-risk, such as a credential or instruction-override language.

SKILL.md

---
name: support-triage
description: Classify an inbound support ticket and route it to the right queue.
---

# Support triage

Read the ticket, assign a severity, and route it.

Full API reference

Every endpoint, parameter, and response shape is published as an OpenAPI 3.1 document.