Skills - Guild

Skills are reusable content packages that teach agents how to perform specific tasks. Each skill contains markdown instructions that get injected into an agent’s context at runtime, giving it domain-specific knowledge — like a tone guide, a compliance checklist, or a debugging runbook. The agent only sees the title and description, allowing for it to understand when to inject the body content into its context. Skills are owner-scoped (owned by a user or organization), versioned with semantic versioning, and private by default.

Create a skill

guild skill create <name>

In interactive mode, the CLI prompts you for an overview. You can also pass it directly:

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

Flag	Description
`--owner <account>`	Owner account name or ID. Defaults to your account.
`--overview <text>`	Short description for display and search. Required in non-interactive mode.
`--public`	Make the skill visible to all users. Requires admin privileges.

The skill is created with a qualified name in the format owner~skill-name (e.g. myorg~tone-guide). Use this name to reference the skill in other commands. Skill names must start with a lowercase letter (a-z). After the first character, names can contain lowercase letters, numbers, hyphens (-), underscores (_), and periods (.). Names are limited to 100 characters.

Add a version

Skills use semantic versioning. Each version contains the markdown body — the actual instructions an agent receives at runtime.

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

Flag	Description
`--version-number <semver>`	Semantic version (e.g. `1.0.0`). Must be greater than the latest existing version.
`--description <text>`	Tells the runtime when to activate this skill. This is what the LLM sees to decide if the skill is relevant.
`--body <text>`	Inline markdown content.
`--body-file <path>`	Read the markdown content from a file.

The description is runtime-facing — it tells the agent when to use the skill. The skill’s overview is human-facing — it appears in search results and listings. Keep them distinct.

In interactive mode (TTY without flags), the CLI prompts for each field.

List versions

guild skill version list myorg~tone-guide

Versions are listed newest-first. Use --limit and --offset for pagination.

Get version details

guild skill version get <version-id>

Manage skills

Get skill details

guild skill get myorg~tone-guide

You can also pass a skill UUID instead of the qualified name.

List skills

guild skill list
guild skill list --search "tone"
guild skill list --sort updated
guild skill list --owner myorg

Flag	Description
`--search <query>`	Search by name, overview, or owner.
`--sort <field>`	Sort by `name` (default), `updated`, or `newest`.
`--owner <id>`	Filter by owner account.
`--limit <number>`	Results per page (default 20).
`--offset <number>`	Pagination offset.

Search skills

Use guild skill search to find skills by keyword across names, overviews, and owners.

guild skill search "compliance"
guild skill search "tone guide" --published
guild skill search "runbook" --sort newest --limit 10

Flag	Description
`--sort <field>`	Sort by `updated` (default), `newest`, or `name`.
`--published`	Only show published skills.
`--limit <number>`	Number of results to return (default: 20).
`--offset <number>`	Offset for pagination (default: 0).

The default output is a formatted table. Pass --json to receive a JSON response with items and pagination fields.

Update a skill

guild skill update myorg~tone-guide --overview "Updated brand voice guidelines"
guild skill update myorg~tone-guide --public
guild skill update myorg~tone-guide --no-public

Flag	Description
`--overview <text>`	Update the description.
`--public`	Make the skill public (requires admin).
`--no-public`	Make the skill private.

Archive and unarchive a skill

Archiving a skill removes it from the catalog. Agents can no longer discover or activate it until you unarchive it.

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

Archived skills are not deleted. All versions remain intact and the qualified name is preserved.

Visibility and permissions

Skills are private by default. Only the owner and their organization members can view and use them. Making a skill public requires account admin privileges. Public skills are visible to all Guild users.

Action	Who can do it
Create	Owner or account admin
View	Owner, organization members, or everyone (if public)
Update	Owner or account admin
Create version	Owner or account admin
Archive/Unarchive	Owner or account admin

Typical workflow

# 1. Create the skill
guild skill create compliance-checklist \
  --overview "SOC 2 compliance checks for code review"

# 2. Write your skill content
# (create a markdown file with the instructions)

# 3. Publish the first version
guild skill version create myorg~compliance-checklist \
  --version-number 1.0.0 \
  --description "Use when reviewing code for SOC 2 compliance violations" \
  --body-file compliance-checklist.md

# 4. Iterate — update content and bump the version
guild skill version create myorg~compliance-checklist \
  --version-number 1.1.0 \
  --description "Use when reviewing code for SOC 2 compliance violations" \
  --body-file compliance-checklist-v2.md

JSON output

All skill commands support --json for machine-readable output:

guild skill list --json
guild skill get myorg~tone-guide --json
guild skill version list myorg~tone-guide --json

​Create a skill

​Add a version

​List versions

​Get version details

​Manage skills

​Get skill details

​List skills

​Search skills

​Update a skill

​Archive and unarchive a skill

​Visibility and permissions

​Typical workflow

​JSON output

Create a skill

Add a version

List versions

Get version details

Manage skills

Get skill details

List skills

Search skills

Update a skill

Archive and unarchive a skill

Visibility and permissions

Typical workflow

JSON output