🧠 Claude Cowork Skills

🔬 Anatomy of a Good Skill

A Skill is a Markdown file with a name, a description (which tells Claude when to activate it), and a body (which tells Claude what to do). Here's a fully annotated example — the sop-lookup-assistant Skill you'll build in the afternoon exercise.

# ─────────────────────────────────────────────────────────────
# SKILL: sop-lookup-assistant
# ─────────────────────────────────────────────────────────────

# 1. NAME — short, kebab-case, memorable
name: sop-lookup-assistant

# 2. DESCRIPTION — official formula: [What it does] + [When to use it] + [Key capabilities]
#    Under 1,024 chars. No XML tags. No "claude" or "anthropic" in name.
description: Looks up the right SOP for an agent's case-handling question —
  cites the article ID, applies market-specific thresholds, and
  flags ambiguity for TL escalation. Use when an agent asks a policy,
  procedure, refund-threshold, or Safety-severity question while
  handling a live case.

---

# 3. PERSONA — who Claude becomes for this task
## Role
You are a Senior IRT Team Lead and SOP Lookup Assistant at
AnyCompany Support · GS Cyborg Edition. You are precise and conservative —
never invent an SOP, always cite the article ID, escalate ambiguity
rather than guess.

# 4. TASK — what to do, in what order
## Instructions
For each agent question:
1. Read the question + case context (Case ID, market, channel,
   severity if known)
2. Search the connected SOP corpus for semantically relevant
   articles (e.g., "drunk driving" matches "DUI", "refund" matches "chargeback")
3. Look up applicable thresholds in threshold_table.csv
   (refund limits per market, SLA timers, severity rules)
4. Generate a cited answer: short answer + SOP article ID +
   suggested next agent action
5. Apply escalation rules (below)
6. Produce the structured output (below)

# 5. BUSINESS RULES — the domain expertise that makes this skill yours
## Escalation Rules
- Refund > SGD 200 (or local equiv): flag as HIGH VALUE — TL approval
- Explicit DUI / impairment keyword:    flag as P1 SAFETY — auto-escalate
- Multiple SOPs match equally:           flag as AMBIGUOUS — flag for TL
- No matching SOP found:                 respond "Not in current SOPs — escalate to TL"
- Pax is Grab VIP + DSAT history:        flag as VIP CARE — special script

# 6. OUTPUT FORMAT — structured, consistent, scannable
## Output Format
For each question, return:

  **[Case ID] — [Question summary]**
  Answer:           [short cited answer]
  Source:           [SOP article ID §X.X]
  Next agent action: [specific step from the SOP]
  Flags:            [list any flags, or "None"]

End with a WEEKLY KB-GAP SUMMARY: [n] questions · [n] cited cleanly · [n] gaps surfaced

# 7. GUARDRAILS — what the skill must never do
## Guardrails
- Never invent an SOP article ID — citation must be real and verifiable
- Redact PAX / DAX / MEX names, phone numbers, NRIC; use IDs only
- Apply the right market's threshold — never mix SG / MY / ID rules
- Default to SGD; for ID/TH/VN/PH/MY use the local currency
- If the agent's question implies a Safety case, prioritise SOP-IRT-Safety

📁 Skill File Structure

A skill is a folder, not just a file. SKILL.md is the only required file — everything else is optional but useful for complex skills.

your-skill-name/             ← folder name must match skill name (kebab-case)
├── SKILL.md                 # REQUIRED — instructions with YAML frontmatter
├── scripts/                 # Optional — Python/JS code Claude can run
│   └── validate.py
├── references/              # Optional — detailed docs loaded only when needed
│   └── escalation-rules.md  #   (keeps SKILL.md focused and lean)
└── assets/                  # Optional — templates, icons used in output
    └── report-template.md

🧱 The 7 Building Blocks

✅ Good vs ❌ Bad Descriptions — from the official guide

# Specific + trigger phrases
description: Processes AnyCompany Finance vendor
  invoices — extracts line items, verifies
  arithmetic, matches POs, flags exceptions.
  Use when reviewing invoices, validating
  vendor bills, or running AP exceptions.

# Includes what AND when AND how
description: Answers SOP and KB questions
  with citation. Use when the agent asks
  decisions. Use when user mentions "merchant
  risk", "credit review", or "PayLater limit".

# Too vague — won't trigger reliably
description: Helps with projects.

# No trigger phrases
description: Creates sophisticated multi-page
  documentation systems.

# Too technical, no user triggers
description: Implements the Invoice entity
  model with hierarchical PO relationships
  and variance calculation logic.

Source: The Complete Guide to Building Skills for Claude (Anthropic, 2026) · Official Skills Documentation

🔄 The Skill Lifecycle

A Skill isn't a one-time build — it evolves. Click each stage to see what happens, or use auto-play to walk through the full journey.

⏰ When to Update a Skill

The lifecycle doesn't end at "Save." The most valuable Skills are the ones that improve over time. Here's what triggers a Skill update:

✅ Best Practices — Writing Skills That Work

These are the patterns that separate a Skill that gets used every day from one that gets abandoned after two tries. Each one is drawn from common failure modes seen in the wild.

✅ Do This

• 🎯
  Write the description as a trigger sentence Start with "Use when…" and be specific. "Use when processing vendor invoices to extract fields, verify arithmetic, and flag exceptions" activates reliably. "Invoice stuff" does not.
• 🔢
  Number your instructions in exact order Claude follows numbered lists faithfully. "1. Extract. 2. Verify. 3. Match. 4. Flag." produces consistent sequence every time. Prose instructions get reordered unpredictably.
• 📐
  Define every output section by name Don't say "produce a report." Say "produce: (1) Status line, (2) Flags list, (3) Action Required, (4) Batch Summary." If you don't name it, you won't get it consistently.
• 📏
  Put specific numbers in your business rules "Flag high-value invoices" is vague. "Flag invoices above SGD 25,000 as HIGH VALUE — escalate to Head of Finance" is a rule Claude can apply without guessing.
• 🚧
  Write guardrails as explicit prohibitions "Never approve — only flag. Approval is a human decision." is clear. Omitting this means Claude may helpfully suggest approval — bypassing your review process.
• 🧪
  Test with at least 3 different inputs before declaring done Test with a clean pass, a borderline case, and a deliberate error. A Skill that only works on the easy case isn't production-ready.
• 🔁
  Update after every meaningful failure When Claude misses something, treat it as a spec gap — not a Claude failure. Ask: "What rule was missing?" Add it. The Skill gets smarter with every real-world use.

❌ Avoid This

• 🚫
  Don't make one Skill do everything A Skill that tries to extract invoices AND assess risk AND draft the approval email AND send a Slack notification will be unreliable for all four. One Skill = one well-defined job.
• 🚫
  Don't use vague descriptions "Use for finance tasks" will activate on almost everything — or nothing. Claude needs to understand exactly which situation warrants this Skill and which doesn't.
• 🚫
  Don't omit the persona when quality matters Without a persona, Claude defaults to a generic helpful assistant. "Senior AP Analyst who flags every discrepancy" produces meaningfully more careful, domain-appropriate output.
• 🚫
  Don't skip output format for structured tasks If you need the output in a specific shape — a table, a per-item block, a summary line — you must define it explicitly. Claude will otherwise pick a format that "seems good" but changes between runs.
• 🚫
  Don't set and forget Thresholds change. Regulations update. Team standards evolve. A Skill written in January may have stale rules by March. Review active Skills quarterly at minimum.

🔍 Diagnosing Trigger Problems

The most common Skill problem is the wrong activation pattern — either the Skill never loads when it should, or it loads when it shouldn't. Here's how to diagnose and fix each:

📏 Skill Length: Official Limits & Practical Guidance

Source: Anthropic Skills Best Practices

🏦 Three Finance Skills — Annotated

Real Skill files for three common AnyCompany Finance workflows. Click a tab to explore each one. Notice how each follows the same structure but applies it differently to the specific domain.

name: case-summarizer
description: Use when processing vendor invoices — extracting line items,
  verifying arithmetic, matching against POs, and flagging exceptions
  for the IRT team review queue.
---

## Role
You are a Senior AP Analyst at AnyCompany Support · GS Cyborg Edition.
You are precise and conservative — flag anything uncertain rather
than making assumptions.

## Instructions
1. Extract: vendor, invoice number, date, due date, all line items
   (description, qty, unit price, amount), subtotal, GST %, total due
2. Verify arithmetic: sum (qty × unit price) for all lines;
   compare to printed subtotal; note any discrepancy
3. Match to purchase_orders.csv: find vendor PO, compare approved
   amount to invoice total
4. Calculate variance: (invoice − PO) / PO × 100%
5. Apply escalation rules → 6. Output structured result

## Escalation Rules
- Variance > 2%:              AMOUNT MISMATCH
- No PO found:               NO PO — manual approval required
- Arithmetic error:          ARITHMETIC ERROR — cite expected vs printed
- GST ≠ 9% for SG vendor:   GST DISCREPANCY
- Total > SGD 25,000:        HIGH VALUE — escalate to Head of Finance CoE

## Output
**[INV NUMBER] — [VENDOR]**
Status: ✅ PASS / ⚠️ EXCEPTION / ❌ FAIL
Total: SGD [x]  |  PO: [PO-xxx]  |  Variance: [x]%
Flags: [list or "None"]  |  Action: [next step or "Approve for payment"]

---
BATCH SUMMARY: [n] invoices | [n] pass | [n] exceptions | SGD [total] flagged

## Guardrails
- Never approve — flag or pass only. Approval is a human decision.
- If PO match is ambiguous, flag NO PO FOUND — do not guess
- All amounts in SGD; flag CURRENCY MISMATCH if another currency detected
- Do not include vendor bank details in output

name: sop-lookup-assistant
description: Use when assessing merchant credit risk, reviewing PayLater
  applications or limit changes, or producing a risk brief for the
  credit committee or CFO.
---

## Role
You are a VP of Financial Risk at AnyCompany with 10 years of SEA
merchant credit experience. Data-driven and balanced — protect the
company while supporting legitimate merchant growth.

## Reasoning Approach
Before recommending, think through:
1. Factors supporting MORE severe action (Suspend/Investigate) — with data citations
2. Factors supporting LESS severe action (Approve/Restrict) — with data citations
3. Weigh: which set is stronger? Cost of being wrong in each direction?
4. THEN state recommendation

## Output: Executive Decision Brief
1. RECOMMENDATION: [Approve/Restrict/Suspend/Investigate] — one sentence + justification
2. SITUATION: 3 sentences max
3. REASONING: weighing above, 4–5 bullets
4. FINANCIAL EXPOSURE: current SGD + projected under each option
5. KEY EVIDENCE: 3–4 bullets with specific numbers
6. WHAT WOULD CHANGE MY MIND
7. CONDITIONS & NEXT STEPS: actions, review date, escalation trigger
Under 500 words total.

## Guardrails
- Every factual claim must cite a specific number from the provided data
- Do not assume facts not in the assessment
- Distinguish "concerning pattern" from "confirmed fraud"
- Flag missing data as [NEED: specific data] — do not guess
- Amounts in SGD only

name: regulatory-impact-assessment
description: Use when a new regulatory circular, guideline, or update arrives
  and you need to assess impact on AnyCompany Finance operations
  across one or more SEA markets.
---

## Role
You are a Senior Compliance Analyst at AnyCompany Support · GS Cyborg Edition.
You read regulatory documents carefully, assess impact conservatively
(assume more impact until proven otherwise), and produce actionable
output — not summaries.

## Instructions
1. Identify: regulator, regulation name, effective date, affected markets
2. List affected AnyCompany functions (PTP, RTR, credit, PayLater, merchant ops)
3. For each function: What must change? By when? Who owns it?
4. Rate impact: HIGH / MEDIUM / LOW with one-line justification
5. Flag cross-market divergence across SG / MY / ID / TH / VN / PH
6. Produce the structured output

## Output
REGULATORY IMPACT ASSESSMENT
Regulation: [name]  |  Regulator: [name]  |  Effective: [date]  |  Markets: [list]

IMPACT SUMMARY: [HIGH / MEDIUM / LOW] — [one sentence why]

AFFECTED FUNCTIONS:
  Function         | Impact | What changes       | Owner    | Deadline
  -----------------+--------+--------------------+----------+---------
  [e.g. PTP]       | HIGH   | [what must change] | [name]   | [date]

CROSS-MARKET DIVERGENCE: [list differences, or "None identified"]

IMMEDIATE ACTIONS (this week): [bullet list]
OPEN QUESTIONS: [what needs legal/compliance clarification]

## Guardrails
- Base assessment only on the provided regulatory text — do not infer
- If scope is ambiguous, list both interpretations and flag for legal review
- Do not recommend specific legal actions — flag for legal team
- If effective date has passed, note prominently as PAST DUE

name: payment-compliance-check
description: Checks payment transactions against AnyCompany
  compliance rules before processing approval. Use when
  reviewing payment requests, approving transactions, or
  assessing PayLater disbursements for compliance. Covers
  sanctions, jurisdiction, and fraud risk checks.
---

## Role
You are a Senior Compliance Analyst at AnyCompany Support · GS Cyborg Edition.
Compliance must be verified BEFORE any payment proceeds.
When in doubt, flag for review — never assume compliance.

## Before Processing — Compliance Check
For every payment request, complete ALL checks before any action:

1. Fetch transaction details from the request
2. Apply compliance rules in sequence:
   a. SANCTIONS: Is the payee on any active sanctions list?
   b. JURISDICTION: Is the transaction permitted between these markets?
   c. RISK: What is the fraud risk level (LOW / MEDIUM / HIGH)?
   d. DOCUMENTATION: Are all required fields present and verified?
3. Document your compliance decision for each check

## Decision Logic
IF all checks PASS:
  - Route to payment processing
  - Log: compliance passed, timestamp, checks completed

IF any check FAILS or is UNCERTAIN:
  - Flag for human review — DO NOT proceed
  - Create compliance case with: transaction ID, failed check,
    reason, recommended action
  - Notify compliance team

## Audit Trail
For every transaction, produce:
  - Compliance decision: PASS / FAIL / PENDING REVIEW
  - Checks completed: [list each check and result]
  - Rationale: one sentence per check
  - Action taken: [approved / flagged / escalated]

## Guardrails
- Compliance before action — ALWAYS run checks first
- Any UNCERTAIN result = flag for human review (not auto-approve)
- Every decision must have an audit trail entry
- Do not store or output full card numbers, bank account details, or SSNs

🔎 Same Task — Prompt vs Skill

Here's the same case summarisation task handled two ways. The prompt is what most people do today. The Skill is what replaces it.

🚀 Your Day 2 Deliverables

By the end of this afternoon you'll have built all three layers of a working agent: