Agent Skillsskill-base April 21, 2026

Agent Skills Series (6): After launch—how to run it: triggers, conflicts, and versions (operating playbook)

About this series

Parts 1–4 covered why Skills matter, how to write them, how to ship them, and what deserves to be a Skill; Fragmentation covered systemic risk when many tools coexist. This post fills a practical gap: how to keep a Skill usable after it ships.

How to narrow triggers (fewer false positives / missed activations)
How to layer content (the boundary between SKILL.md and references/)
How to govern conflicts (same name, same category, same scenario)
How to iterate versions (the rhythm from v0 to v1)

1. Align on the goal first: not “written,” but “does not drift long term”

Many teams ship a first Skill that works—then it stops working two weeks later. The usual cause is not “the model got worse,” but that you never treated the Skill as an evolvable asset.

After launch, aim for three verifiable outcomes:

Hit rate: activate when it should; do not steal turns when it should not.
Consistency: similar requests produce a stable structure across people and sessions.
Rollback: when a change hurts quality, you can return to the last good version fast.

Without these three, a Skill is just a lucky prompt.

2. `description` is routing, not a product blurb

description decides whether the Skill gets used.

Use a fixed three-part shape:

Scope: exactly which tasks this Skill handles.
Trigger scenarios: which user intents should turn it on.
Keyword examples: common phrasing (two to six is enough).

Example (copy-paste friendly):

---
name: weekly-team-brief
description: >-
  Produce a weekly team progress brief (this week / next week / blockers).
  Use when the user asks for a weekly report, a weekly sync note, an exec
  brief, or mentions this week’s progress, next week’s plan, or blockers.
---

Anti-pattern (do not write like this):

---
name: writing-helper
description: Helps write all kinds of content and improve communication quality.
---

Why this fails: it will fight every other “writing” Skill for triggers—who wins becomes luck.

3. Main file vs references: short spine + long attachments

One rule: the main file decides; attachments hold detail.

SKILL.md: task taxonomy, hard constraints, process skeleton, acceptance checklist.
references/*.md: long templates, glossaries, long examples, FAQs.
scripts/: deterministic actions (format conversion, batch jobs, fixed checks).

Move content into references/ when:

It is a long code block or sample that exceeds one screen.
Background the model can skip without losing the “first-step” decision.
Long guidance reused by multiple templates.

The benefit is not aesthetics—it matches progressive disclosure: light discovery first, expand after a hit.

Reference: Agent Skills docs (progressive disclosure)

4. Checklists are not decoration—they are regression guards

If you add only one mechanism, add a checklist.

Use two layers:

Global checklist (SKILL.md): every output must pass it.
Scenario checklist (references/*.md): applies only to a given template.

Minimal global template:

## Acceptance checklist
- [ ] Task type identified and mapped to a single template
- [ ] Minimum context filled (audience, time window, goal)
- [ ] Hard constraints and forbidden items respected
- [ ] Output structure matches template length and format
- [ ] Uncertain information called out explicitly

Keep checklists to about five items. Fifteen items means nobody runs them.

5. Conflict governance: classify first, then avoid “many Skills, same scenario”

The common pitfall in multi-Skill teams is not bad writing—it is too many Skills in the same category.

A simple layering model reduces collisions:

Base rules (one to two): shared team constraints (package manager, directories, security red lines).
Scenario flows (split by scenario): e.g. weekly brief, FAQ, retrospective, release notes.
Project vertical (split by project): project-only helpers, component rules, directory boundaries, term mappings.
Personal prefs (optional): individual workflows, not team defaults.

Keep project vertical in its own group; do not mix it into global rules. Project rules change fast and couple deeply—if they sit with global rules, they pollute trigger scope. Safer patterns:

State the project boundary in description (project name, repo, module).
Put project-only component lists, shared-method call conventions, and common anti-patterns in references/.
Add a checklist line: “Are we cross-project misusing a component or method?”

Anthropic’s official skill-creator is a good structural reference: split references/, scripts/, assets/, agents/ in the tree instead of cramming everything into one SKILL.md—better extension.

Governance rules:

Within a layer, one primary Skill per scenario.
Same Skill name is never allowed.
If two Skills duplicate a scenario, merge—do not keep both.

Read alongside Fragmentation for the fuller multi-tool conflict picture.

6. Versioning: small steps, not a “big rewrite”

A simple rhythm:

v0.1: hit the right triggers first.
v0.2: add checklists and forbidden items (less drift).
v0.3: split references (less noise in the main file).
v1.0: freeze interfaces and naming once stable.

Each change should do one class of work:

Either triggers (description)
Or process (body structure)
Or detail (references/)

Do not mix all three in one edit—or you will not know which change hurt quality.

7. A launch checklist you can copy

Before release, run these seven checks:

Is description narrow enough and does it include trigger keywords?
Can you read the SKILL.md spine in two to three minutes?
Have long sections moved into references/?
Is there a global checklist?
Do templates have scenario checklists?
Is there a failure path when information is missing (what to ask)?
Is there a rollback-friendly version for this change?

Only after these pass is “does it feel good?” worth discussing.

8. If you are driving adoption in a team, suggested order

Ship one high-frequency scenario as v0.1.
For two weeks, watch only hit rate and consistency.
Then add checklists and split references.
Only then push team-wide distribution and versioning.

This is steadier than designing a “perfect skill system” on day one.

Series map (sibling posts)

Part	Post	What it covers
1	Pain points and motivation	Why Skills
2	Concepts in practice	`SKILL.md`, progressive disclosure, minimal examples
3	Tooling	skill-base / `skb` distribution and install
4	What deserves a Skill	Topic criteria and counterexamples
5	Admin query page case study	A project-level Skill refactor example
Extra	Fragmentation	Governance when many tools coexist