A skill is a capability manual.

A skill is a capability manual for an agent.

It tells the agent how to use tools safely and consistently for a specific capability. It should not do the work itself; it should guide the agent to the right tools, state, rules, and outputs.

A skill should define

When to use it

Example: use this skill when the user asks to analyze a mortgage AI use case.

Which tools to call

Example: load_session, compute_fact_gaps, audit_rules, and approve_rule.

What state matters

Example: confirmed_facts, asked_fact_keys, rule_id, status, and resweep_status.

What invariants must be preserved

Example: never approve a draft rule without human confirmation.

What the user should see

Example: a compact verdict, the next question, a risk summary, or an approval packet.

What should stay internal

Example: raw tool payloads, internal scoring, and intermediate state.

What to do when something fails

Example: if state is incomplete, ask for one missing fact. If a tool fails, stop and explain.

A skill should not be

• A hardcoded conversation script
• A long workflow document
• Business logic written in prose
• Raw SQL instructions
• A replacement for tools
• The source of truth
• The only place where safety rules exist

Skill = when to act + which tools to use + what state to respect + what rules never to break

The clean split

• Skill = manual
• Agent = orchestrator
• Tool = executor
• Database or session = source of truth
• Guard or hook = enforcement
• Human = approval authority

Keep it simple

A good skill is not:

First ask this, then ask that, then follow these 40 steps.

It is:

• Use this capability when X.
• Call these tools.
• Read and write this state.
• Preserve these invariants.
• Show this type of answer.
• Stop if the guard fails.