Skills

Skills are reusable knowledge packages that agents can draw on at runtime. Each skill contains markdown instructions — like a tone guide, compliance checklist, or debugging runbook — that get injected into an agent’s context when relevant. Unlike workspace context, which is always included, skills are activated on demand. The agent sees a catalog of available skills and their descriptions, and decides which ones to pull in based on the current task.

How skills work

Agents built with the current Guild Agent SDK can use skills through the SDK’s native skillsTools runtime tools:

skills_search — browses the skill catalog. Returns metadata only (name, description, version), not the full body.
skills_activate — loads a specific skill version. The full markdown body is returned and placed into the agent’s context.

New TypeScript LLM agents created from the Guild CLI scaffold include skills support by default. If you are wiring a TypeScript LLM agent manually, include skillsTools in the agent’s tools:

import { llmAgent, skillsTools } from "@guildai/agents-sdk"

export default llmAgent({
  description: "Uses account-scoped skills when relevant.",
  tools: {
    ...skillsTools,
  },
  systemPrompt: "Use relevant account skills before answering.",
})

Older agents may need to be rebuilt with a recent SDK version or updated to include skillsTools. Remove skillsTools if the agent should not use account skills. Goose recipe agents also support skills. Declare them in the recipe’s skills field, and the runtime materializes each declared skill so the agent can load it on demand. OpenClaw agents support skills too, but ship them with the agent instead of declaring them: commit a skills/<name>/SKILL.md in the agent’s files and the runtime discovers it from the workspace.

The older guildai~skills integration still exists for compatibility with legacy agents and non-SDK runtimes. For TypeScript LLM agents, use skillsTools instead of manually adding the integration.

This follows a progressive disclosure model: the agent sees a lightweight catalog for discovery, then loads the full instructions only when needed. When an agent runs:

The skill catalog is attached to the skills_search tool description, showing available skills and their descriptions
The agent reads the catalog and decides if any skill is relevant to the current task
If so, it calls skills_activate to load the full markdown body into its context

Skills are account-scoped — any skill owned by your user or organization account is available to agents running in your workspaces, as long as the agent includes skills support through the SDK. Publishing an agent does not bundle its skills for other organizations. If another organization installs your agent, that organization also needs the relevant skills created or imported into its own account for the agent to discover and activate them.

Write skill descriptions as activation instructions for the agent. For example: “Use when reviewing code for SOC 2 compliance violations” tells the agent exactly when to pull in the skill.

Version references

When activating a skill, the agent can reference it in several ways:

Reference	Behavior
`myorg~skill-name`	Resolves to the latest version
`myorg~skill-name@*`	Resolves to the latest version
`myorg~skill-name@1.2.3`	Pins to a specific version

The default flow is for the agent to use the exact version returned by skills_search. Explicit version pinning is only needed when you want to lock a skill to a known-good version.

Limitations

Skills are knowledge-only. A skill can instruct an agent on how to use tools it already has, but it cannot add new tools, grant capabilities, or execute code. Think of skills as reference documents, not plugins.

Skills vs. Workspace context

	Workspace Context	Skills
When included	Always, every session	On demand, when relevant
Scope	One workspace	All workspaces in the account
Best for	Project background, team conventions	Domain-specific instructions, reusable playbooks
Managed via	Web UI or CLI	Web UI or CLI

Use workspace context for information every agent needs in a workspace. Use skills for specialized knowledge that only matters for certain tasks.

Managing skills

Skills are created and versioned through the Guild CLI. You can also edit skill details, change scope, and archive skills through the web UI. Skills have a single Owner — the user or organization that created them. Unlike agents, skills do not have a separate maintainer role.

# Create a skill
guild skill create tone-guide --overview "Brand voice and messaging guidelines"

# Publish a version with your markdown content
guild skill version create myorg~tone-guide \
  --version-number 1.0.0 \
  --description "Use when drafting user-facing copy or messaging" \
  --body-file tone-guide.md

Each version is immutable — to update a skill’s content, publish a new version with a higher version number. The agent always uses the latest version. See the CLI skills guide for the full command reference.

Edit skill

To edit a skill’s name or overview, open the skill in the web UI and click Edit skill. Changes to the overview take effect for agents on their next run.

Versions in the web UI

Creating a skill also publishes its first version, 1.0.0. To publish a new version, open the skill and click Edit skill. The Create New Version modal shows the agent description alongside a Markdown editor for the skill content, and an unsaved-changes bar appears once you start editing. Click Commit Changes to publish. Each commit increments the major version — 1.0.0 becomes 2.0.0, then 3.0.0. The web UI does not produce minor or patch versions. Use guild skill version create --version-number when you need a specific number. Use the version picker in the editor to browse earlier versions and inspect their content and description.

Scope skill

By default, skills are available to agents across all workspaces in your account. Use Scope skill in the web UI to restrict a skill to specific workspaces.

Archive and unarchive

Archiving a skill removes it from the catalog so agents can no longer discover or activate it. Archived skills are not deleted — all versions remain intact and can be restored. To archive or unarchive a skill, open the skill in the web UI and click Archive or Unarchive. You can also do this from the CLI:

guild skill archive myorg~tone-guide
guild skill unarchive myorg~tone-guide

Settings

Open a skill’s Settings to manage its visibility (public or private) and scope configuration. Only the skill owner or an account admin can change these settings.

Making a skill public is permanent. Once a skill is public, you cannot change its visibility back to private. Attempting to change is_public from true to false is rejected with a 403 Forbidden error. Only operators can bypass this restriction.

Liking skills

You can express appreciation and track popular skills using likes.

Click the Heart icon in the header of any skill’s detail page to like or unlike it.
The total number of likes appears next to the Heart icon in the header, and under the Stats column in the main skills list.

Overview

The Smith

The Factory

Platform

Insights

Agent SDK

How skills work

Version references

Limitations

Skills vs. Workspace context

Managing skills

Edit skill

Versions in the web UI

Scope skill

Archive and unarchive

Settings

Liking skills

​How skills work

​Version references

​Limitations

​Skills vs. Workspace context

​Managing skills

​Edit skill

​Versions in the web UI

​Scope skill

​Archive and unarchive

​Settings

​Liking skills

How skills work

Version references

Limitations

Skills vs. Workspace context

Managing skills

Edit skill

Versions in the web UI

Scope skill

Archive and unarchive

Settings

Liking skills