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:

1. Domain Expertise — Industry-specific rules, edge cases, unwritten conventions
2. 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:

1. Domain & Purpose — What problem? What industry standards apply?
2. Ontology Requirements — What system-specific structures must the skill understand?
3. Content Source — Conversation, docs, specifications, or files to distill from?
4. Automation Potential — What can be deterministic (scripts)? What needs interpretation (LLM)?
5. 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