Qualified Name

• A qualified name is Guild's global naming convention: owner~resource-name, with a tilde as the separator between the owner and the resource.
• Every named object on Guild — agents, workspaces, skills, integrations, services — is addressable by its qualified name. It is how one thing points to another across the whole platform.
• Examples: guildai~the-smith is Guild's built-in assistant, myorg~my-agent is one of your organization's agents, myorg~tone-guide is a skill your team owns.
• Qualified names are how you avoid collisions between teams and how the CLI, API, and app all agree on which specific resource you mean.

A qualified name is the fully addressable identifier for a resource on Guild. It has two parts joined by a tilde: the owner and the resource name. The owner is a user or an organization. The resource name is the specific object owned by that account.

The format is deliberately compact and readable: guildai~the-smith, myorg~tone-guide, acme~release-notes-agent. You see qualified names everywhere on Guild — in CLI commands, in service imports, in the URLs of published resources, in configuration files. They are the platform's shared vocabulary for talking about specific things.

Qualified names exist because names alone are not enough. Two organizations can both have an agent called release-notes. Without a namespace, the platform has no way to tell them apart. With a namespace, acme~release-notes and globex~release-notes are unambiguously different objects, even if the humans call them the same thing in conversation.

Every named resource has an owner

Users and organizations are owner accounts. When you create an agent, a skill, or an integration, it is owned by the account you're acting under (or an org you specify with --owner). The resource's qualified name is composed automatically: <owner>~<name>.

The tilde is the separator

Guild uses a tilde (~) between owner and resource name because it is unambiguous and safe across the URLs, filenames, and CLI arguments qualified names show up in. It is not a slash (which conflicts with paths), not a dot (which conflicts with domain-like syntax), and not a colon (which conflicts with URLs). The tilde reads as "belonging to" and stays out of the way.

Qualified names work anywhere Guild talks about a resource

You see qualified names in CLI arguments (guild workspace chat --agent owner~agent-name), in service imports for coded agents (import { gitHubTools } from "@guildai-services/guildai~github"), in trigger creation, in skill references, and in inter-agent handoffs (@mention owner~agent-name in chat). Anywhere Guild needs to point at a specific resource, it uses the qualified name.

Skill and agent names follow the same rules

A qualified name's resource segment must start with a lowercase letter and can contain lowercase letters, numbers, hyphens, underscores, and periods. Max length is 100 characters. The rules apply to skills, agents, and other user-created resources so names stay predictable across CLIs, URLs, and imports.

Namespaces prevent silent collisions

Any platform that supports multiple organizations will eventually have two teams naming things the same way. Without namespacing, that is a bug waiting to happen. Qualified names put the collision resolution in the syntax itself: acme~release-notes and globex~release-notes are always different, no matter how many teams call something "release-notes."

Ownership is explicit at the point of reference

When a CLI command or a config file references a resource, the owner is right there in the name. You do not have to look up "which release-notes agent is that" — the qualified name says. Debugging, audits, and access-control decisions all get faster when ownership is visible in every reference.

Cross-account sharing gets a coherent model

Guild lets accounts publish resources for others to consume — a skill your org publishes so other Guild users can install it, an agent Guild itself publishes for anyone (like guildai~the-smith). Qualified names give shared resources a stable, unambiguous address so consumers know exactly what they are using.

The convention scales to services and platform resources

Beyond user-created resources, Guild's own services use the same convention. Service imports in coded agents look like @guildai-services/guildai~github. Platform-owned agents live under guildai~. One convention covers user resources, org resources, and platform resources with no special cases.

Reference an agent in a workspace chat

guild workspace chat --agent owner~agent-nameguild workspace chat --agent owner~agent-name --workspace owner~workspace-name

Both --agent and --workspace take qualified names. There is no --owner flag on these commands because the owner is already part of the name.

Fork an existing agent to customize it

guild agent init --fork owner~agent-name

Point at the source agent by its qualified name. The forked copy becomes yours under your account.

Reference a skill by qualified name

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
guild skill version list myorg~tone-guide

Skills follow the same owner~name pattern. Once created, always reference the skill by its qualified name (or, alternatively, by its UUID).

Import a service in a coded agent

import { gitHubTools } from "@guildai-services/guildai~github"

Service packages use the qualified name of the underlying service (guildai~github) as the module path segment. Same convention, different surface.

Choose owner names carefully

The owner segment of a qualified name is usually your organization's account name, and it becomes part of every resource you publish. Pick something short, unambiguous, and consistent with how you refer to your team elsewhere.

Resource names have character rules

Lowercase letters to start, then lowercase letters, numbers, hyphens, underscores, and periods. Max 100 characters. Guild will reject names that violate the rules at create time.

Qualified names are stable identifiers

Renaming a resource changes its qualified name, which breaks every reference to the old name across the platform. Prefer good names up front to renames later.

UUIDs work anywhere qualified names do

Every resource also has a UUID, and Guild's CLI accepts a UUID in place of a qualified name. Qualified names are for humans; UUIDs are for automation and long-term stability.

Guild is a control plane for AI agents, a place to build, deploy, and govern the agents your teams run in production. Qualified names are the shared vocabulary that lets every resource on the platform — agents, skills, workspaces, services — reference every other resource unambiguously.

• The CLI getting-started guide shows qualified names in action across workspace, agent, and skill commands.
• Skills use owner~skill-name just like agents use owner~agent-name.
• Workspaces, triggers, and sessions all reference their agents by qualified name.
• Explore the Guild CLI and the rest of the platform at guild.ai.