Skills (Guild context)

• Skills are reusable, versioned Markdown content packages you attach to agents. At runtime, the agent decides when to inject a skill's body into its context based on the skill's description.
• An agent sees only a skill's title and description by default. The full body is pulled in only when the description is relevant to what the agent is doing, so context stays small until it needs to be big.
• Skills are how teams share reusable knowledge across many agents: a brand voice guide, a compliance checklist, a debugging runbook, an issue-labeling policy for GitHub.
• Skills are owner-scoped (owner~skill-name), semver-versioned, and private by default. They are created, versioned, and shared through the Guild CLI.

A skill in Guild is a reusable content package that gives an agent domain-specific knowledge. Each skill contains Markdown instructions — a brand voice guide, a compliance checklist, an internal glossary, a step-by-step debugging runbook — and any agent can be equipped with the skill so it has access to those instructions when needed.

The key move is that skills are not always in context. An agent sees only a skill's title and description most of the time. When the agent decides the description is relevant to the task at hand, it pulls the skill's body into its context. Skills scale to hundreds of packages without blowing up the context window on every session, because most of them stay dormant.

Skills are owner-scoped, meaning they belong to a user or organization and are addressed with a qualified name like myorg~tone-guide. They are versioned with semver so you can ship updates without breaking agents pinned to older versions. And they are private by default; making a skill public requires an explicit flag and admin privileges.

Title, description, and body: three layers of visibility

Every skill has three surfaces. The name and overview show up in listings and search, so humans can find the skill. The description is what the LLM sees at runtime — it is the signal the agent uses to decide when the skill applies. The body is the actual Markdown instructions, injected into the agent's context only when the description matches what the agent is trying to do.

This separation matters. The description is written for the model. The overview is written for a person browsing your organization's skill library. Both should be clear, but they are addressed to different audiences and should read differently.

Runtime injection based on description relevance

When an agent runs, Guild presents the model with the titles and descriptions of every skill the agent has access to. The model decides whether any of them are relevant to the current turn. If it decides one is, that skill's body is added to the context, and the agent has the full instructions to work from.

This is why the description field is called "runtime-facing." It is not documentation. It is a decision aid the LLM uses in real time to pick the right knowledge for the moment.

Semver versioning with pinning

Skills use semantic versioning. Each version has a version number, a description, and a body. An agent can be pinned to a specific version so an unrelated skill update never changes the agent's behavior, and version history is preserved so you can roll back.

Owner-scoped and private by default

Skills are owned by an account (a user or an organization) and namespaced with the owner~name convention. Private is the default so an internal compliance skill does not leak to the rest of the ecosystem. Making a skill public requires the --public flag and admin privileges on the owner account.

Shared knowledge should not be per-agent

Teams that build more than a handful of agents run into the same problem: the same brand voice, the same compliance rules, the same domain vocabulary end up copy-pasted into every agent's instructions. That is fragile and expensive to change. Skills give you one canonical source you attach where it applies.

Runtime relevance keeps context small

Static instructions in an agent's prompt use tokens on every single call, whether relevant or not. Skills only enter context when the model decides they are needed. That means an agent can carry a library of dozens of skills at low baseline cost, and pay only for what actually gets pulled in.

Versioning turns institutional knowledge into a product

A brand guide, a customer-support playbook, a review checklist — all of these change over time. Treating them as versioned skills, rather than free-form prompt text, means changes are auditable, agents can pin to stable versions, and rollback is a real option instead of a git-archaeology exercise.

Skills are how one team's expertise scales to many agents

Your legal team owns the compliance skill. Your brand team owns the voice skill. Your platform team owns the debugging runbook skill. Each is written once, versioned, and attached to every agent that needs it. When the source of truth changes, so does every agent, without anyone editing an agent.

Create a skill

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

The overview is human-facing and shows up in listings and search. Owner defaults to your account; add --owner to create the skill under an organization.

Add a version with real instructions

guild skill version create myorg~tone-guide \  --version-number 1.0.0 \  --description "Guides the agent to use brand-appropriate tone and messaging" \  --body-file tone-guide.md

The description is what the LLM sees to decide whether to activate the skill. The body-file contains the actual Markdown instructions the agent gets when the skill is pulled in.

List and search skills

guild skill list                  # All skills you can seeguild skill list --search "tone"  # Text searchguild skill list --sort updated   # Sort by most recent updateguild skill list --owner myorg    # Filter by owner

Get details on a skill or a version

guild skill get myorg~tone-guideguild skill version list myorg~tone-guideguild skill version get <version-id>

The description is prompt engineering, not documentation

The description field is runtime-facing — the LLM reads it and decides whether to pull the skill's body into context. Write it like an instruction: "Use this skill when the user asks about brand voice, tone, or messaging." A vague description means the skill never gets activated, or gets activated at the wrong times.

Overview and description are not the same

The overview is for people. It shows up in search results and skill listings so a teammate can find the skill and understand what it does. The description is for the model. Keep them distinct, and make each address its own audience clearly.

Version numbers must move forward

Each new version must be greater than the latest existing version in semver. You cannot re-publish a version number. If you need to change a shipped version, publish a new one and update pinned agents accordingly.

Private by default is the safe default

Making a skill public requires --public and admin privileges. Do not flip this by accident on a skill that contains internal policy, customer data, or proprietary content. Public skills are visible across Guild.

Naming rules matter

Skill names must start with a lowercase letter and can contain lowercase letters, numbers, hyphens, underscores, and periods. Max 100 characters. Qualified name is owner~skill-name.

Guild is a control plane for AI agents, a place to build, deploy, and govern the agents your teams run in production. Skills are how one team's expertise is turned into a versioned, reusable, on-demand piece of context that every agent in the organization can draw on when it matters.

• The Skills guide in the CLI docs is the full walkthrough of creating, versioning, and managing skills.
• Skills attach to agents that run inside a workspace, alongside workspace context and triggers.
• Explore the Guild CLI and the rest of the platform at guild.ai.