Expert Skill Creation

Transform expert knowledge into production-ready skills that combine domain expertise with system-specific understanding.

Why Skills Fail in Production

AI assistants fail not because they lack intelligence, but because they lack:

Domain Expertise — Industry-specific rules, edge cases, unwritten conventions
Ontology Understanding — How YOUR systems, data structures, and workflows actually work

Both are required. Domain knowledge without system context produces generic output. System knowledge without domain expertise produces structurally correct but semantically wrong results.

Workflow

Assess → Discover (Expertise + Ontology) → Design → Create → Refine → Ship

Quick Assessment

Create a skill when:

Used 3+ times (or will be)
Follows consistent procedure
Saves >300 tokens per use
Requires specialized knowledge not in Claude's training
Must produce trusted output (not "close enough")

Don't create for: one-time tasks, basic knowledge Claude already has, rapidly changing content.

Discovery: Two Streams

Stream 1: Domain Expertise

Deep knowledge that transcends any specific company:

Industry standards and their versions
Professional conventions and best practices
Edge cases only practitioners know
Validation rules from specifications

Example (LEDES validation): LEDES 98B vs XML 2.0 formats, UTBMS code taxonomy, date format requirements, required vs optional fields.

Stream 2: Ontology Understanding

How the skill maps to specific systems and organizations:

Company-specific policies and constraints
Data structures and identifiers unique to the system
Cross-references between entities (timekeepers → IDs → rates)
Workflow states and transitions

Example (LEDES validation): Firm-specific timekeeper codes, matter numbering conventions, approved billing rates, outside counsel guideline requirements.

Discovery Questions

When starting, I'll ask about:

Domain & Purpose — What problem? What industry standards apply?
Ontology Requirements — What system-specific structures must the skill understand?
Content Source — Conversation, docs, specifications, or files to distill from?
Automation Potential — What can be deterministic (scripts)? What needs interpretation (LLM)?
Complexity Level — Simple (SKILL.md only), Enhanced (+scripts), or Full (+resources)?

Skill Architecture

skill-name/
├── SKILL.md              # Layer 1: Core (300-500 tokens)
├── scripts/              # Layer 0: Automation (0 tokens to run)
│   └── validate.py
└── resources/            # Layer 2: Details (loaded selectively)
    └── ADVANCED.md

Layer 0 (Scripts): Free execution, structured JSON output Layer 1 (SKILL.md): Loaded when triggered - keep lean Layer 2 (Resources): Fetched only when specific section needed

Token Optimization

Technique	Instead of	Do this	Savings
Scripts	500 tokens explaining validation	`python scripts/validate.py`	~450 tokens
Reference	Inline schema (200 tokens)	Link to `resources/schema.json`	~185 tokens
Layer 2	Everything in SKILL.md	Link to `resources/ADVANCED.md`	~750 tokens

Description Formula

<Action> <Object> for <Purpose>. Use when <Trigger>.

Example: "Validate billing data for system migration. Use before importing invoices."

Shipping

When content is finalized:

python scripts/package_skill.py skill-name 1.0

Creates skill-name-v1.0.zip with:

DIRECTORY_STRUCTURE.txt (auto-generated)
README.md with deployment instructions
All skill files properly organized

Templates & Examples

See resources/templates/ for:

Minimal skill template
Enhanced skill template
Script template

See resources/examples/ for domain-specific patterns.

Quality Checklist

Before shipping:

Description <30 tokens
SKILL.md <500 tokens (Layer 1)
Scripts for deterministic operations
Advanced content in resources/ (Layer 2)
Version in frontmatter
All referenced files exist

Version: 2.2 | Target: <500 tokens Layer 1

create-expert-skill