Skills: authoring & publishing

A skill is instructions plus the files that go with them, packaged so any agent can pick it up. Writing one is mostly writing a good SKILL.md.

Who can do what

Task	User	Agent owner	Admin
Create and edit a skill	✅	✅	✅
Upload files into a skill	✅	✅	✅
Change a skill's status	—	—	✅
Change a skill's visibility scope	—	—	✅
Let an agent author skills	—	—	✅
Delete a skill	—	—	✅

Anyone can write a skill; publishing decisions belong to admins. See Skills governance.

What's in a skill

skill-name/
├── SKILL.md        # required — instructions, with YAML frontmatter
├── scripts/        # optional — code for deterministic or repetitive steps
├── references/     # optional — docs loaded into context when needed
└── assets/         # optional — templates, icons, fonts used in output

SKILL.md carries frontmatter and then the instructions:

---
name: quarterly-report
description: Produce the quarterly board report in house style. Use when asked
  for a board report, quarterly summary, or QBR deck.
---

# Quarterly report

Instructions for the agent…

Field	Required	Purpose
name	Yes	Identifier, kebab-case
description	Yes	How the agent decides to use it
compatibility	No	Runtime requirements, e.g. python3, network

The description is the whole game

Nothing else determines whether a skill actually gets used. It's matched against what the user asked for, so it must name both what the skill does and when to reach for it — in the words people actually use.

Be a little pushy. Agents under-trigger skills; list the keywords and scenarios explicitly.

❌ description: How to build a dashboard to display data.

✅ description: Build an interactive metrics dashboard. Use when asked for a dashboard, a metrics view, a KPI page, or "show me the numbers over time".

All the "when to use" information belongs in the description, not the body. The body is read after the agent has decided to use the skill; the description is what makes that decision.

Writing the instructions

• Explain the why, not just the steps. An agent that understands the intent handles the case you didn't anticipate; one following steps blindly doesn't.
• Use the imperative. "Read the template first" beats "the template should be read first."
• Put reference material in references/. It's loaded when needed rather than always, which keeps the skill cheap.
• Put deterministic work in scripts/. If a step is the same every time, a script does it identically and for no tokens — better than asking the model to redo it correctly each run.

Statuses

Status	Meaning
Draft	Being worked on; not for general use
Pending review	Submitted, awaiting an admin
Active	Available for agents to use
Deprecated	Still works, shouldn't be adopted
Archived	Retired

An admin sets the status. Draft → Active is the moment a skill becomes real for the organization.

Visibility

Private (creating organization only), Tenant (all agents in that organization), or Public (discoverable by any organization). Admins control this — see Skills governance.

Agents that write skills

An agent can author skills if an admin has turned that on for it. Then you can say "turn what we just worked out into a skill" and it will, which is the fastest way to capture a procedure while it's fresh.

It's off by default. An agent that can create skills can create things other agents will pick up, so it's a deliberate grant.

Testing

Attach the skill to an agent and ask for the work in the words a real user would. Two failure modes, with different fixes:

• The agent ignores the skill — the description doesn't match the request. Fix the description.
• The agent uses it and gets it wrong — the instructions are ambiguous, or the agent lacks a tool the skill needs. Check tools first.