Skills
Manage workspace skills and skill sources — create, import from any GitHub repository, enable, disable, sync. Covers permissions, authentication, the MCP tool surface, and sync scheduling.
This page covers the operational mechanics of Skills: where to manage them, how to register a skill repository, how authentication works for public versus private sources, and what the MCP tool surface looks like to an agent.
Workspace admins manage skills at Settings → AI → Skills. The page has two sections:
- Skill Sources — every skill repository visible to the workspace, including the built-in
cloudposse/atmossource and any custom sources configured for the workspace. - Skills — every individual skill, grouped by source, with per-skill enable/disable toggles and provenance badges.
Both sections are gated on the
ws:skills:manage permission (workspace owner or admin). Members can read skills (so they see them in the slash menu and through MCP) but cannot create, edit, or toggle them.Click New skill in the Skills section. A workspace skill needs four things:
- Slug — the slash command users type (e.g.
triage,release-readiness). Lowercase, alphanumeric plus hyphens, unique within the workspace. - Name — human-readable label shown in the slash menu and settings list.
- Description — short summary the agent reads to decide whether to load the skill. Treat this as load-bearing: write it so an agent picking between several skills can route correctly from this line alone.
- Prompt body — the instructions the agent receives when the skill is invoked. Voice, structure, output expectations, and any artifact-creation rules (e.g. "call
create_pdfto persist the final document").
A workspace skill with the same slug as a system skill shadows the system skill: lookups by slug return the workspace version first. Clone a system skill from the Skills section to start from its prompt and customize it.
Skill repositories are external GitHub repos that Atmos Pro syncs on a schedule. The directory shape is documented in Skills — Skill repositories.
Atmos Pro includes the built-in
cloudposse/atmos source for every workspace. Custom source registration is currently handled through manual admin setup while the self-serve source-management UI is rolling out. A source is configured with:| Field | Example | Notes |
|---|---|---|
| Owner | cloudposse | GitHub user or org. |
| Repository | atmos | Repo name only. |
| Ref | main | Branch, tag, or commit. Pinning to a tag freezes the version; pinning to a branch tracks updates. |
| Path | agent-skills/skills | Path inside the repo to the directory containing per-skill subdirectories. |
| Display name | Atmos Skills | Shown in Settings and on per-skill provenance badges. |
When a source is configured, Atmos Pro enqueues a sync. Once the sync finishes, matching skills appear in the workspace's catalog.
Atmos Pro uses one of two auth modes per source:
- 1Workspace installation token (private repos). If the Atmos Pro GitHub App is installed on the exact source repository and linked to the current workspace, Atmos Pro can read the repository. This is the only path that works for private repositories.
- 2Anonymous public fetch (public repos). If no workspace-linked installation exists, Atmos Pro reads the public repository without using another workspace's GitHub installation.
If authentication fails, Atmos Pro shows the error on the source row in Settings.
Private repositories require the Atmos Pro GitHub App installed on the exact source repository and linked to the workspace — there is no other way for Atmos Pro to read the content. Install the App on the repo first, then ask an admin to configure the skill source. The sync will pick up the workspace-linked installation automatically.
If you remove the App installation later, subsequent syncs will fall back to public mode and start failing with 404s on the private repository. Atmos Pro will surface the error on the source row in Settings.
Built-in sources (the seeded
cloudposse/atmos) are visible to every workspace. A workspace can hide an entire source from its own catalog without affecting other workspaces:- Toggle the source's Visibility off in Settings. Every skill under that source disappears from the slash menu and from MCP
list_skillsfor that workspace. - Per-skill enablement state is preserved while the source is hidden. Toggle visibility back on and prior choices restore.
For workspace-added sources, hiding the source has the same effect — without deleting the source row, so an admin can experiment with disable/enable without losing their import configuration.
Skills under any source can be toggled individually from the Skills section.
When a source is first synced into a workspace, every skill it ships is enabled by default. Workspaces opt out, not in. Implementation-wise, an "enabled" skill is one with no explicit override row in
skill_system_disables (for system-scoped skills, including all imported skills) or with enabled = true on the row (for workspace-authored skills).Disabling a skill removes it from:
- The slash-command menu in the dashboard chat.
- The MCP
list_skillscatalog andget_skilllookups for the workspace.
Disabled skills stay in Settings so admins can re-read or re-enable them later. They are not deleted.
Each source has a Reset to source defaults action that drops every per-skill enablement override the workspace has for skills under that source. After a reset the workspace sees the source's default state (everything enabled).
Each source row has a Sync now button (admin-only). Clicking it enqueues a sync for that source.
Atmos Pro also keeps enabled sources up to date on a schedule.
Atmos Pro's sync is permissive about SKILL.md frontmatter. Missing
name falls back to the directory name; missing description falls back to the first paragraph of the body; malformed YAML in the frontmatter block is shown as a warning but the body imports anyway.This matters when importing skills authored elsewhere — a
SKILL.md written for a different ecosystem still imports cleanly even if its frontmatter doesn't match exactly what Atmos Pro expects.Five MCP tools expose skills to agents, all read-only and gated on the
ws:skills:read permission (granted to every workspace role by default):| Tool | What it returns |
|---|---|
list_skills | Enabled skills visible to the workspace, with slug, name, description, version, and source provenance. Honors source visibility and per-skill enablement. |
get_skill | A single skill's prompt body plus its references index. Workspace skills shadow system skills with the same slug. |
list_skill_references | Supporting examples, notes, and reference files bundled with a skill. |
get_skill_reference | The body of a single supporting reference file under a skill. Loaded on demand so the system prompt stays lean. |
search_skills | Search across visible skill bodies and references. Lets the agent find a skill by topic before loading it. |
| Capability | Permission | Default roles |
|---|---|---|
Read skills (slash menu, MCP list_skills / get_skill / list_skill_references / get_skill_reference / search_skills) | ws:skills:read | ws:owner, ws:admin, ws:member |
| Create, edit, clone, delete workspace skills | ws:skills:manage | ws:owner, ws:admin |
| Add, edit, delete skill sources; toggle visibility; sync now | ws:skills:manage | ws:owner, ws:admin |
| Toggle individual skill enablement | ws:skills:manage | ws:owner, ws:admin |
Skills frequently produce a durable output (a PDF postmortem, an incident brief, a release-readiness checklist). Skills that produce artifacts call the corresponding MCP create tool —
create_pdf for now — and the result lands in the workspace's artifacts inbox attributed back to the skill that produced it. See Chat artifacts for the artifact tool catalog.- Skills (concept) — what skills are and how they fit together.
- MCP Server (concept) — what MCP unlocks for an agent.
- MCP Server (configuration) — installation, OAuth, tool catalog.