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
Skills are exposed through the guildai~skills integration. Agents that declare this integration as a dependency get access to two 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.
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 the guildai~skills integration.
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 |
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 | CLI |
Managing skills
Skills are created and versioned through the Guild CLI.
# 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
