Skills

What's the difference between an AI that answers questions and one that runs your workflow?

A skill packages a repeatable workflow into a single slash command. Instead of re-prompting the same instructions every session, you invoke /review-pr or /commit — the AI follows a predefined set of steps, quality gates, and output formats. One command. Consistent results.

Better tools make better skills. Better skills make better Units of Work. Better Units of Work create more valuable outputs and outcomes.

Unit Of Work

A Unit of Work is incompressible value: the smallest action of value.

A skill is not the Unit of Work. A skill is the reusable capability used to perform, review, or improve the Unit of Work. The standard defines the fitting: inputs, outputs, proof, and the next interface the result must connect to.

Tool -> Skill -> Unit of Work -> Valuable Output -> Outcome

Example:

Layer	Example	Standard Question
Tool	Link checker, browser, model, CLI, database	Can the skill act with enough leverage?
Skill	fix-links, kb-edit-playbook, validate-demand	Is the method repeatable and gated?
Unit of Work	Fix broken internal links in one docs page	Is this the smallest action of value?
Output	Page with valid links and no broken routes	Can the next workflow consume it cleanly?
Outcome	Reader stays in flow; agent trust increases	Did the work create value?

The standard matters because the Unit of Work must connect to the next Unit of Work without translation. That is the business-engineering equivalent of fittings in physical engineering.

Part of the Flow KB — the Agency-layer facet: a clean skill registry is laminar routing; a crowded one is turbulence.

How Skills Work

AI coding tools like Claude Code expose skills as slash commands. Each skill contains:

• Instructions — the steps the AI must follow
• Quality gates — what "done" looks like before the AI reports success
• Argument hints — what input the skill expects (a file path, a PR number, free text)
• Trigger phrases — natural language that activates the skill automatically

The pattern is composable. A publishing workflow might invoke /fix-links, then /review-pr, then /commit — all from a single /publish command. Small, correct skills chain into larger workflows.

Tool quality sets the ceiling. If the tool cannot inspect the right state, write the right artifact, or verify the result, the skill becomes a script-shaped wish. If the tool is precise, observable, and well-scoped, the skill can become a reliable business capability.

Horizontal Craft, Vertical Judgment

The skill floor is T-shaped.

• Horizontal skills encode portable tools and methods. They teach a craft that several domains can reuse.
• Vertical skills encode situated judgment. They know the buyer, industry, public surface, operating constraint, and proof boundary.

Writing demonstrates the joint:

writing-clarity + writing-rhetoric + writing-narrative
  -> belief-* | biz-dev-* | biz-mkt-* | ux-* | industry skills

Do not move every skill that produces words into writing-*. A writing method teaches the craft. A vertical skill applies that craft in context and owns the consequences.

The Living Capability Loop

The Playbook and skill rail improve each other:

public doctrine -> operational skill -> domain use -> output -> proof
  -> question -> improved public doctrine

The Capability System adds the missing business edge. It asks which human capability the skill augments, which business outcome consumes its output, who governs consequential decisions, and what evidence should change the relationship. A skill without those edges is an orphan method, even when it executes perfectly.

This is a virtuous feedback loop. The Playbook explains what good looks like. The skill makes it repeatable. Real work exposes variance. The lesson returns to the Playbook and lifts the next run's baseline.

Skill Judgement

A skill deserves attention only when it changes future work enough to justify its load. Skill design is not a writing exercise. It is a load-placement decision across the human, the model, and the system.

Run the checks in order before adding, promoting, or expanding a skill. First shrink the routing surface. Then move branch-only detail out of the common path. Only after those two moves should you merge, retire, or add skills.

Check	Question	Good signal
Trigger	Who should remember to invoke it: the human, the model, or a rail?	The trigger prevents repeated drift without bloating routing.
Structure	What belongs in the common path, and what belongs in reference?	The main skill stays short; branch detail loads only on need.
Steering	Which phrase changes the agent's next action?	The phrase appears in plans, tool choices, or output shape.
Pruning	Would behavior change if this paragraph disappeared?	No-op text, stale caveats, and duplicated rules are removed.

This is the skill version of a decision journal. Record the context, option, call, expected effect, and falsifier.

Then treat the skill as a node in the context graph:

• Which workflow invokes it?
• Which output changes?
• Which proof reads it?
• Which later decision should learn from it?

The most common failure is adding a skill when the right move is smaller:

• Sharpen the description.
• Move branch-only material into a reference file.
• Strengthen one leading phrase.
• Delete text that no longer changes behavior.

When a skill registry gets crowded, treat the budget problem as a routing problem, not a prose problem. The next action is to find silent drains, verbose descriptions, and cold skills before changing the architecture.

Changes my mind: A workflow cannot name its trigger, output, proof gate, or consumer after three real uses.

The Market Pattern

Any instruction a team repeats more than three times is a candidate for a skill.

Without skills — re-prompt every session, inconsistent output, knowledge lives in one person, slow onboarding.

With skills — one invocation per workflow, gates enforce quality, skill is shareable across the team, new hires invoke rather than learn.

Skills shift AI from a question-answering tool to a workflow execution engine. The difference is whether judgment is embedded in the skill or re-applied every time.

Skill Maturity

Not all skills are equal. A maturity model applies:

L0 — Idea — exists as a repeated manual prompt

L1 — Defined — written down with steps and gates

L2 — Connected — invoked consistently across sessions

L3 — Tested — has caught at least one error via a gate

L4 — Proven — zero manual interventions, measurable improvement

L4 skills are institutional knowledge, encoded. They outlast any individual contributor.

Audit Skills Before Trusting Them

A valid skill is not necessarily useful. Structural validation proves that the package can load. It does not prove that the skill improves decisions or behavior.

Run these gates in order:

Gate	Question	Evidence
Structure	Can the skill load safely?	An official validator checks names, frontmatter, descriptions, file size, and unique evaluation IDs.
Coverage	Does the registry cover distinct jobs?	Classify each skill by type and domain. Flag competing pairs and domains with no owner.
Drift	Does the deployed skill match its canonical source?	Compare file digests. Classify every difference as a source advance, stale projection, or divergent local work.
Behavior	Does the skill improve performance on the job it claims to own?	Run paired treatment and control cases with the model, harness, prompts, and repetitions frozen.
Claim	Is the measured change strong enough to trust?	Apply thresholds fixed before the run. Report regressions, authority violations, token cost, and elapsed time.

Structural Checklist

Check every skill against the Agent Skills specification:

• The directory name uses lowercase kebab-case and matches the frontmatter name.
• name is 1–64 characters and uses kebab-case.
• description is 1–1024 characters. It states what the skill does, when to use it, and the trigger words that should route work to it.
• Frontmatter parses as valid YAML.
• SKILL.md stays under 500 lines where practical. Move branch-only detail into references/.
• evals/evals.json exists, parses as JSON, and contains unique case IDs.
• Optional allowed-tools, license, and compatibility fields are well formed.
• The skill passes skills-ref validate at the pinned commit with no errors.

Use the Agent Skills reference implementation for the validator. Pin its commit so a validator update cannot silently change the audit standard between runs.

Passing this checklist proves conformance, not value. Continue through coverage, drift, behavior, and claim gates before judging the skill.

Use a capability taxonomy to expose overlap. A practical starting set is:

1. Library or API reference
2. Product verification
3. Data fetching and analysis
4. Business-process automation
5. Code scaffolding
6. Code quality and review
7. CI/CD
8. Decision framework
9. Other

Two skills with the same type and domain are not automatically duplicates. They are a competing pair that needs a consumer and boundary review. A domain with no owner is a coverage gap.

Run A Paired Behavioral Pilot

Test only skills that are new, edited, or disputed. Use at least six case types:

• positive routing;
• missing context;
• non-triggering;
• collision with an adjacent skill;
• authority boundary;
• null behavior.

Run each case with the skill enabled and disabled. Repeat each arm three times. Keep the model, harness, and prompts unchanged. Record the full result, token use, and elapsed time for every run.

Mark a skill as improved only when it:

• beats a discriminating expectation in at least two of three repetitions;
• introduces no regression or authority violation; and
• wins most blinded pairwise comparisons.

A tie or zero measured change is hold. A structural pass alone never earns an improved claim. Report cost even when accuracy rises; extra tokens and time are part of the result.

Run structural, coverage, and drift checks whenever the skill directory changes. Repeat behavioral pilots when the skill changes, the model or harness changes, or a high-traffic skill reaches its review date. Skill value decays when its environment changes.

Failure Modes

• Prompt wrapper — the skill hides an improvised prompt without gates, evidence, or reusable outputs.
• Workflow theater — the skill moves work between tools but does not shrink the Unit of Work or improve the outcome.
• Stale command — the tool, model, or route changes and the skill keeps producing outputs nobody can consume.
• Skill bloat — the skill pays model attention for instructions that are rare, branch-only, stale, or already handled by another rail.

Context

• Writing — a horizontal capability family that demonstrates portable methods composed by vertical skills
• Prompts — the building blocks under skills
• Autonomous Agents — when tasks need agents, not skills
• Coding Tools — where skills run
• Standards — the AAIF skill specification
• Platform — the Tight Five connection that decides whether a skill can become a reliable capability
• Decision Journal — the decision trace pattern behind skill changes
• Context Graphs — how skill decisions become queryable precedent

Questions

Next question: What's the highest-value repeatable workflow in your current work that hasn't been packaged as a skill yet?

• How do you decide when a workflow is stable enough to package as a skill versus keeping it as an improvised prompt?
• What's the difference between a skill that saves time and one that moves the work somewhere else?
• If L4 skills encode institutional knowledge — what happens to that knowledge when an AI tool is deprecated?
• Which skill would get better if you deleted one paragraph instead of adding another?