Skills

What it is. A knowledge package for an agent: a folder of Markdown and text files committed to your repo that the agent opens on demand instead of carrying it all in the system prompt.

Use it when an agent needs reference material that outgrows a system prompt: a style guide, a runbook, a language reference, an internal API guide. The agent sees a one-line catalog entry and reads the full content only when it decides to.

Works with agents (attached via skills:), profiles (narrowed per profile), and deploys (git push or swirls deploy ships the files with your project).

A skill block declares a knowledge skill resolved from .agents/skills/<name>/ in your repo. Skills are knowledge only: text the agent reads, not code the agent runs.

The skill block

The skill block is a top-level declaration. There is no type: field; the keyword identifies the block.

skill swirls_lang {
  name: "swirls-lang"
}

Field reference

The block name (swirls_lang) is the handle agents reference in skills:. The name: value ("swirls-lang") is the folder on disk. They differ because block names cannot contain hyphens.

Attach a skill to an agent

List skill block names in the agent's skills: field. It is a bare-identifier array, same style as tools:.

secret vendor_keys {
  vars: [OPENROUTER_API_KEY]
}

skill swirls_lang {
  name: "swirls-lang"
}

agent helper {
  label: "Helper"
  secrets: vendor_keys
  model: "openai/gpt-4o-mini"
  skills: [swirls_lang]
  system: @ts {
    return "You answer questions about Swirls. Open the swirls-lang skill before writing any .swirls code."
  }
}

A profile may narrow skills: to a subset of the agent's list, the same rule as tools:.

agent helper {
  secrets: vendor_keys
  model: "openai/gpt-4o-mini"
  skills: [swirls_lang, support_playbook]

  profile support {
    skills: [support_playbook]
  }
}

Authoring on disk

Skills live under one canonical root in your repo, relative to where you deploy from:

.agents/skills/<name>/
  SKILL.md
  rules/
    style.md
    naming.md

Only .agents/skills/ is read. Skill trees under .cursor/ or .claude/ are not.

SKILL.md is required and carries frontmatter that names and describes the skill:

---
name: swirls-lang
description: How to write correct .swirls files. Open before writing any Swirls DSL.
---

# Swirls language

Start with the strict syntax rules...

The name and description frontmatter feed the agent's skill catalog. The directory name is authoritative; a frontmatter name that differs from the directory slug is a warning, not an error.

Install skills however you like: hand-write them, clone them, or copy them from another repo. The platform reads whatever is committed at deploy time.

Knowledge only

Skills carry text, not programs. These are rejected at swirls doctor and at deploy:

• Files with shebang lines (#!)
• Script file extensions
• scripts/ or bin/ paths inside the skill tree
• Symlinks, or paths that escape the skill directory

Size caps

Exceeding a cap is a deploy error.

Validation

swirls doctor resolves each declared skill block to .agents/skills/<name>/ and checks the tree:

Deploy

Deploy with git push or swirls deploy. The deploy collects every referenced skill tree alongside your .swirls files, verifies the content is knowledge only, and stores it content-addressed for runtime reads. A referenced skill directory that is missing from the deployed source fails the deploy with an explicit message.

How agents read skills at runtime

Skills load progressively, so an unused skill costs almost nothing per turn:

The platform serves skill reads directly. Reading a skill never starts the agent's sandbox, so chat turns that only consult skills stay fast and cheap.

Common mistakes

Referencing the directory slug in skills:

skills: takes skill block names as bare identifiers. Directory slugs with hyphens are not valid identifiers and quoted strings do not resolve.

// Incorrect
agent bad_agent {
  model: "gpt-4o"
  secrets: llm_creds
  skills: ["swirls-lang"]
}

// Correct
skill swirls_lang {
  name: "swirls-lang"
}

agent good_agent {
  model: "gpt-4o"
  secrets: llm_creds
  skills: [swirls_lang]
}

name: with a path

The name: field is a single directory slug. Nested paths and traversal are rejected.

// Incorrect
skill bad_skill {
  name: "shared/swirls-lang"
}

// Correct
skill good_skill {
  name: "swirls-lang"
}

Scripts in the bundle

A skill tree with executable content fails validation. Skills are read, never run. To give an agent code to execute, use tool workflows or a sandbox.

Profile skills not a subset

A profile's skills: must be a subset of the agent's skills:. Listing a skill only in the profile is a validation error.

// Incorrect: support_playbook is not on the agent
agent bad_agent {
  model: "gpt-4o"
  secrets: llm_creds
  skills: [swirls_lang]

  profile support {
    skills: [support_playbook]
  }
}

// Correct
agent good_agent {
  model: "gpt-4o"
  secrets: llm_creds
  skills: [swirls_lang, support_playbook]

  profile support {
    skills: [support_playbook]
  }
}

Skill directory missing at deploy

The .agents/skills/<name>/ directory must be committed and present in the deployed source. A declared skill with no directory fails the deploy.

Further reading

• Agents: The agent block, tools, profiles, and how a turn runs.
• MCP servers: Remote tools for agents, the sibling extension point.
• Swirls Cloud: Projects, deploys, and the hosted platform.