Writing Your First AI Skill in 15 Minutes

You don’t need a platform, a certification, or an engineering team to start encoding your expertise for AI agents. You need a text editor, 15 minutes, and a decision your team makes repeatedly.

This tutorial walks you through writing a real, production-quality Skills-as-Documents artifact from scratch. By the end, you’ll have a skill that an AI agent can read and execute: no code, no infrastructure, no waiting.

The Template

Every skill follows this structure. Copy this template, fill it in, and you have a working skill.

# [Skill Name]

## Purpose
[One sentence: what decision does this skill make?]

## Inputs
- [What data does the agent need before it can act?]
- [List each input explicitly]
- [The agent will not guess: it needs to know what to gather]

## Criteria
- [Factor 1]: [how to evaluate] (+/- weight)
- [Factor 2]: [how to evaluate] (+/- weight)
- [Factor 3]: [how to evaluate] (+/- weight)

## Decision Rules
- [Condition]: [Action]
- [Condition]: [Action]
- [Condition]: [Action]

## Exceptions
- [Override condition]: [Override action]
- [Edge case]: [How to handle]

## Examples
### Example 1: [Scenario name]
**Input:** [Describe the input]
**Expected output:** [What the agent should decide]
**Reasoning:** [Why. This teaches the agent the logic]

### Example 2: [Scenario name]
**Input:** [Describe the input]
**Expected output:** [What the agent should decide]
**Reasoning:** [Why]

That’s it. Six sections. Now let’s fill one in.

Step 1: Choose a Repeatable Decision

Pick a decision your team makes at least several times per week. Not a one-off judgment call: a repeatable evaluation that follows a pattern, even if that pattern has exceptions.

Good candidates:

• Qualifying inbound leads
• Reviewing content before publishing
• Routing customer support tickets
• Evaluating vendor proposals
• Approving expense reports
• Triaging bug reports by severity

Bad candidates (for a first skill):

• Annual strategic planning
• Hiring decisions for senior roles
• Crisis response

The difference: good candidates have identifiable criteria, recurring inputs, and a finite set of outcomes. You’re looking for decisions where an experienced person follows a mental framework, even if they can’t articulate it on the spot.

For this tutorial, we’ll build a support ticket triage skill: deciding priority and routing for incoming customer support requests.

Step 2: Define the Purpose

One sentence. What does this skill decide? Be specific.

Bad: “Handle support tickets.” Good: “Evaluate incoming support tickets and assign priority (P1-P4) and routing (engineering, success, billing).”

The purpose scopes the skill. An agent reading “assign priority and routing” knows it’s responsible for two outputs and nothing more. It won’t try to resolve the ticket, draft a response, or escalate to management. Tight purpose means focused execution.

# Support Ticket Triage Skill

## Purpose
Evaluate incoming support tickets and assign priority (P1-P4) and
routing (engineering, customer-success, billing).

Step 3: Define the Inputs

List every piece of information the agent needs before it can make the decision. Don’t assume context. Declare it.

Ask yourself: “If I were training a new hire to do this, what would they need to see before making a call?”

## Inputs
- Ticket subject line and description
- Customer tier (enterprise, growth, starter)
- Product area affected
- Whether the customer reported data loss or security concern
- Number of open tickets from this customer in the past 30 days

Each input is a contract. The agent knows: “I need these five things. If I don’t have one, I ask for it.” No guessing. No hallucinating information that isn’t there.

Step 4: Write the Criteria

This is the core of the skill. What factors does an expert weigh when making this decision?

Interview your best person. Ask: “Walk me through the last five tickets you triaged. What made you decide this one was urgent? What made that one low priority?” Write down the factors. Assign rough weights.

## Criteria
- Data loss or security concern mentioned: P1 override
- Customer tier enterprise: +2 priority levels
- Production environment affected: +2 priority levels
- Workaround available (customer mentions alternative): -1 priority level
- Multiple recent tickets from same customer: +1 priority level (pattern indicator)
- Product area is billing/payments: route to billing
- Product area is technical/API/integration: route to engineering
- Product area is onboarding/usage/account: route to customer-success

Notice the mix: some criteria affect priority, others affect routing, and some do both. That’s real. Business decisions rarely map to a single dimension. The agent reads the full criteria set and synthesizes a result.

Step 5: Add Decision Rules

Map the criteria to concrete actions. What happens at each priority level?

## Decision Rules
- P1 (Critical): Page on-call engineer. Notify customer success lead.
  Response SLA: 1 hour.
- P2 (High): Assign to senior team member in routed department.
  Response SLA: 4 hours.
- P3 (Medium): Add to team queue in routed department.
  Response SLA: 24 hours.
- P4 (Low): Add to backlog. Response SLA: 72 hours.
- Default (insufficient info to assess): Assign P3, route to
  customer-success for initial response and information gathering.

The default rule matters. It tells the agent what to do when the information is ambiguous or incomplete. Without a default, the agent either guesses (bad) or stalls (also bad). Explicit defaults prevent both.

Step 6: Document the Exceptions

This is where skills earn their keep. Exceptions are the “unless” clauses that separate an expert from a beginner.

Ask: “When would you break the normal rules? What situations override the standard process?”

## Exceptions
- Any ticket mentioning "data loss," "breach," or "unauthorized access":
  always P1 regardless of other criteria
- Enterprise customer with active renewal within 60 days: bump priority
  by one level and CC account executive
- Tickets submitted through legal or compliance channels: always P2
  minimum, route to engineering AND customer-success
- Known outage in progress (check status page): auto-tag as P1,
  link to incident, don't create duplicate engineering tickets

Every exception you document here is a scenario that would trip up a rules engine, confuse a junior hire, or get lost in a prompt. In a skill, exceptions are first-class citizens: readable, reviewable, and maintainable.

Step 7: Add Examples

Examples anchor the agent’s interpretation. Abstract criteria produce abstract results. Concrete examples produce consistent results.

Write two or three scenarios: one clear-cut, one that requires weighing factors, and one that triggers an exception.

## Examples

### Example 1: Clear P1
**Input:** Enterprise customer, ticket says "production database returning
errors, cannot process orders, possible data corruption"
**Expected output:** P1, route to engineering, page on-call
**Reasoning:** Production affected + possible data loss = P1 override.
Enterprise tier confirms priority. Engineering handles database issues.

### Example 2: Judgment call
**Input:** Growth customer, ticket says "billing dashboard shows
incorrect totals, doesn't match our records, not urgent"
**Expected output:** P3, route to billing
**Reasoning:** Billing discrepancy is a billing route. Customer says
"not urgent" and growth tier doesn't get auto-bump. No data loss or
security concern. P3 is appropriate: the "not urgent" language plus
workaround availability (they have their own records) keeps it moderate.

### Example 3: Exception trigger
**Input:** Starter customer, ticket says "I think someone accessed
our account without permission, seeing logins from unknown IP"
**Expected output:** P1, route to engineering AND customer-success
**Reasoning:** "Unauthorized access" triggers the security exception.
always P1 regardless of customer tier. Security tickets route to
engineering for investigation plus customer-success for communication.

Those three examples do more to calibrate the agent’s judgment than a page of additional criteria. They show the agent: here’s how we actually apply these rules in practice.

Step 8: Test With an Agent

Hand the complete skill to an AI agent along with a test scenario.

The prompt can be simple: “Read this skill document and apply it to this support ticket: [paste ticket].”

Run five scenarios where you know the right answer. Score the agent:

• Did it get the priority right?
• Did it route correctly?
• Did it catch the exception?
• Did the reasoning make sense?

If the agent matches expert judgment on four out of five, the skill is production-ready. Use the mismatches to refine. Each miss tells you where the skill needs more precision.

The Complete Skill

Here’s the full artifact, ready to commit:

# Support Ticket Triage Skill

## Purpose
Evaluate incoming support tickets and assign priority (P1-P4) and
routing (engineering, customer-success, billing).

## Inputs
- Ticket subject line and description
- Customer tier (enterprise, growth, starter)
- Product area affected
- Whether the customer reported data loss or security concern
- Number of open tickets from this customer in the past 30 days

## Criteria
- Data loss or security concern mentioned: P1 override
- Customer tier enterprise: +2 priority levels
- Production environment affected: +2 priority levels
- Workaround available (customer mentions alternative): -1 priority level
- Multiple recent tickets from same customer: +1 priority level
- Product area is billing/payments: route to billing
- Product area is technical/API/integration: route to engineering
- Product area is onboarding/usage/account: route to customer-success

## Decision Rules
- P1 (Critical): Page on-call engineer. Response SLA: 1 hour.
- P2 (High): Assign to senior team member. Response SLA: 4 hours.
- P3 (Medium): Add to team queue. Response SLA: 24 hours.
- P4 (Low): Add to backlog. Response SLA: 72 hours.
- Default: Assign P3, route to customer-success for triage.

## Exceptions
- "Data loss," "breach," or "unauthorized access": always P1
- Enterprise customer with renewal within 60 days: bump +1 priority,
  CC account executive
- Tickets from legal/compliance channels: P2 minimum, route to
  engineering AND customer-success
- Known outage in progress: auto-tag P1, link to incident

## Examples

### Clear P1
**Input:** Enterprise, "production database errors, cannot process
orders, possible data corruption"
**Output:** P1, engineering, page on-call
**Reasoning:** Production + possible data loss = P1 override

### Judgment call
**Input:** Growth, "billing dashboard incorrect totals, not urgent"
**Output:** P3, billing
**Reasoning:** Billing issue, no urgency indicators, growth tier

### Exception trigger
**Input:** Starter, "someone accessed our account, unknown IP logins"
**Output:** P1, engineering + customer-success
**Reasoning:** Security exception overrides tier. Always P1

Thirty minutes from blank page to a skill that handles 80% of your ticket triage. An afternoon of refinement to reach 95%. And every iteration lives in version control as a permanent record of how your organization’s judgment improves. The Recursive Loop in practice.

That’s Business-as-Code. Instead of a platform you buy or a model you train, a document you write, test, and improve. Start with one. The second one takes ten minutes.