Building High‑Availability Claude Skills: From Core Mechanics to Production‑Ready Development

Meta‑Tool Architecture

Claude provides a special Skill tool (capital S) that sits alongside basic tools such as Bash and Read but works differently. Its core object includes:

const SkillTool = {
  name: "Skill",
  inputSchema: { command: string },
  // Generates the list of available skills at the start of each conversation
  prompt: async () => {
    const allSkills = await getAllAvailableSkills();
    const { modeCommands, regularCommands } = categorizeSkills(allSkills);
    const skillsList = [...modeCommands, ...regularCommands]
      .map(skill => skill.userFacingName())
      .join(", ");
    return `Available skills: ${skillsList}`;
  },
  // Validates the user‑provided command
  validateInput: async (input, context) => {
    const skill = findSkillByName(input.command);
    if (!skill) throw new Error("Skill not found");
    return skill;
  },
  // Checks permissions for the current user
  checkPermissions: async (input, context) => {
    return hasPermission(context.user, input.skill);
  },
  // Generator that yields the skill instructions and a context‑modification event
  call: async function* (input, context) {
    const skill = await validateInput(input, context);
    const skillContent = await readFile(skill.path);
    const { metadata, instructions } = parseSkillFile(skillContent);
    yield { role: "user", content: instructions };
    yield { type: "context_modification", allowedTools: metadata.allowedTools, model: metadata.model };
  }
};

Key points : prompt runs at the start of each conversation and injects a dynamic list of available skills into Claude’s system prompt.

The skill description becomes part of the system prompt as a tool specification. call is a generator that can emit multiple user messages and a context‑modification event.

Difference from ordinary tools :

Ordinary tools are direct action executors; Skill is a prompt injection + context modifier.

Message flow for ordinary tools: assistant → tool_use → user → tool_result. For Skill:

assistant → tool_use Skill → user → tool_result → user → skill prompt → context update

.

Typical message count: 3‑4 for ordinary tools, 5‑10+ for Skill.

Token cost per round: ~100 tokens for ordinary tools, ~1,500+ tokens for Skill.

Context is static for ordinary tools and dynamically modified per session for Skill.

Three‑Level Loading Mechanism (Token‑Efficiency Secret)

Claude Skills use a three‑level loading strategy to minimise token consumption while keeping each skill discoverable.

Level 1 – Metadata : Loaded at startup; only the YAML front‑matter (name, description, allowed‑tools, model flags). Approx. 100 tokens per skill.

Level 2 – Instructions : Loaded only when the skill is triggered; the main body of SKILL.md. Usually < 5,000 tokens.

Level 3+ – Resources : External files (example libraries, standards) are never loaded into the prompt; they are accessed on‑demand via Bash commands, incurring zero token cost.

Level 1 example (YAML front‑matter) :

---
name: pr-review
description: Review code. Triggers when the user says "review".
allowed-tools: Read, Grep, Edit
disable-model-invocation: true
---
## PR workflow
1. Get PR diff
2. Check security issues
3. Generate review report

Why progressive loading? Loading every SKILL.md on each turn would consume ~15,000 tokens for 30 skills (≈500 tokens each). Progressive loading reduces this to ~3,000 tokens (≈100 tokens per skill), saving roughly 80 % of token usage.

Decision logic for loading Level 2 (run only when a skill matches the user input):

async function shouldCallSkill(userInput) {
  const skillMetadata = getAllSkillMetadata();
  const skillsPrompt = skillMetadata
    .map(s => `${s.name}: ${s.description}`)
    .join("
");
  const decision = await llm.infer(`User input: "${userInput}"
Available skills:
${skillsPrompt}
Which skill should be called? (return name or "none")`);
  if (decision !== "none") {
    const skill = loadSkillFullContent(decision); // loads Level 2
    return skill;
  }
  return null;
}

Impact of description on triggering :

# Bad description – never triggers
---
name: code-review
description: This tool checks security, performance, and style.
---
# Reason: description lacks user‑spoken phrases.

# Good description – high trigger rate
---
name: code-review
description: Review code. Triggers on "review", "cr", "审查代码".
---

Zero‑token resource strategy (Level 3) – reference external files via Bash instead of reading them into the prompt:

# Wrong – reads the whole file into the prompt (costs tokens)
const examples = readFile("examples.md");
systemPrompt += examples; // ~3,000 tokens

# Correct – add an instruction that runs a Bash command only when needed
const instruction = `When you need examples, run: \`cat {baseDir}/examples.md\``;
systemPrompt += instruction; // ~100 tokens only

Creating a Production‑Grade Skill from Scratch

Planning checklist (four key questions)

function validateSkillPlan(idea) {
  const questions = [
    "What specific task does this Skill address?",
    "What patterns or rules should Claude follow?",
    "Can I provide 2‑3 concrete examples?",
    "Does this Skill conflict with existing Skills?"
  ];
  // Example of a good vs. bad skill definition
  const goodSkill = {
    task: "Review TypeScript type safety",
    patterns: ["strict type checking", "avoid any", "handle undefined/null"],
    examples: ["review API type definitions", "check error handling"],
    conflict: false
  };
  const badSkill = { task: "Write code", patterns: [], examples: [], conflict: null };
  return { valid: goodSkill, invalid: badSkill };
}

Full SKILL.md skeleton (TypeScript review example)

---
name: typescript-review
description: Review TypeScript code. Triggers on "review ts", "检查类型", "ts审查".
allowed-tools: Read, Grep, Edit
---
# TypeScript Code Review Skill
## Purpose
When the user submits TypeScript code or asks for a review, ensure the code follows the team’s type‑safety standards.
## Instructions
### Type‑safety rules
1. **Enable strict mode**
```typescript
{ "compilerOptions": { "strict": true, "noImplicitAny": true, "strictNullChecks": true } }
```
2. **Avoid <code>any</code>** – use concrete types instead.
3. **Handle undefined/null** – use optional chaining or nullish coalescing.

TypeScript best‑practice examples

// ✅ Correct return type
async function getUser(id: string): Promise<User> {
  return db.user.findUnique({ where: { id } });
}

// ❌ Missing return type – leads to implicit any
async function getUser(id) {
  return db.user.findUnique({ where: { id } });
}

// ✅ Safe optional chaining
const value = data?.nested?.property ?? defaultValue;

// ❌ Direct property access – may throw
const value = data.nested.property;

Debugging checklist when a Skill never triggers

File location – ensure .claude/skills/your-skill/SKILL.md exists.

YAML front‑matter – must start and end with ---. name field – unique and correctly spelled. description – contains natural‑language trigger phrases within the first 250 characters.

Trigger word overlap – avoid conflicts with other Skills.

Six tricks to boost trigger rate

Gold‑spot description : place the most common trigger phrases at the very beginning of the description.

Bilingual triggers : include both English and Chinese phrases.

Cover variations : list synonyms, abbreviations, and common misspellings.

Avoid competition : don’t duplicate built‑in Claude capabilities.

Negation words : explicitly exclude unrelated use‑cases.

A/B test descriptions : rotate multiple description variants in multi‑turn conversations and keep the one with the highest activation rate.

Advanced Enterprise‑Level Skill Architecture

Multi‑Skill collaboration patterns

Pipeline (chained) mode : one Skill suggests the next Skill.

User: "Design a user‑management API"
→ [design-api] generates API definition
→ Suggests review
User: "review it"
→ [typescript-review] checks type safety
→ Suggests test generation
User: "write tests"
→ [test-gen] creates unit tests

Role‑split mode : separate Skills for frontend and backend concerns.

---
name: frontend-review
description: Review frontend code. Triggers on "review frontend", "React review".
allowed-tools: Read, Grep, Edit, Glob
---
---
name: backend-review
description: Review backend code. Triggers on "review backend", "API audit".
allowed-tools: Read, Grep, Edit, Glob
---

Shared resource library : common reference files (e.g., API standards) are stored once and accessed by multiple Skills via Bash commands.

Conditional triggering & context awareness (Smart‑Review Skill)

---
name: smart-review
description: Intelligent code review. Triggers on "review", "审查", "cr".
allowed-tools: Read, Grep, Glob, Bash
---
## Context detection
1. Detect tech stack: `ls package.json tsconfig.json Cargo.toml go.mod pom.xml`
2. Detect lint configs: `ls .eslintrc* .prettierrc*`
3. Get recent changes: `git diff --name-only HEAD~1`
## Stack‑specific checks
- TypeScript: any usage, missing generics, async error handling.
- Rust: ownership, unsafe blocks.
- Go: goroutine safety, error handling.
- Python: type hints, async patterns.
## Change‑size depth
- 1‑3 files: deep per‑file review.
- 4‑10 files: core logic review.
- >10 files: focus on architectural changes.

Version management & team workflow

Store each Skill under .claude/skills/skill-name/SKILL.md with a companion CHANGELOG.md.

Shared standards live in .claude/skills/shared/ with versioned subfolders (v1, v2).

Team process: proposal → forked development → PR review → merge → release announcement.

End‑to‑End Case Study: Full‑Featured Code Review Skill

Requirement analysis

Target audience: full‑stack developers using TypeScript + React.

Core functions: detect type‑safety issues, React anti‑patterns, security flaws, performance bottlenecks.

Trigger phrases: "review", "cr", "审查代码", "帮我看看".

Output: graded report (Critical / Warning / Suggestion) plus summary statistics.

Complete SKILL.md implementation

---
name: code-review
description: Code review. Triggers on "review", "cr", "审查代码", "帮我看看代码", "code review".
allowed-tools: Read, Grep, Glob, Bash
---
# Code Review Assistant
## Trigger conditions
- User submits code snippet and mentions a review keyword.
- Optional file or directory specification.
## Step 1: Environment detection
1. Detect project type: `ls package.json tsconfig.json Cargo.toml go.mod pom.xml 2>/dev/null`
2. Detect lint/config files: `ls .eslintrc* .prettierrc* tsconfig.json biome.json 2>/dev/null`
3. Determine review scope:
   - If user provides a path → review that path.
   - Else run `git diff --name-only HEAD~1`.
   - If no git diff → ask the user.
## Step 2: Stack‑specific checks
### TypeScript/React focus
- **Type safety** – any, type assertions, missing generics.
- **React anti‑patterns** – inline functions, missing keys, stale deps.
- **Error handling** – uncaught promises, unchecked nulls.
- **Security** – dangerouslySetInnerHTML, unsanitised input.
- **Performance** – unnecessary re‑renders, large components.
### General checks (all projects)
- Duplicate logic, naming conventions, missing edge‑case handling, SQL injection / XSS risks.
## Step 3: Report format
```markdown
## Review Report
### Critical (must fix)
[Issue] file:line – description
  Impact: why it matters
  Suggestion: fix proposal
### Warning (recommended)
[Issue] …
### Suggestion (nice‑to‑have)
[Suggestion] …
## Statistics
- Files reviewed: N
- Critical: X
- Warning: Y
- Suggestion: Z
- Quality score: Q/10
```
## Constraints
- No automatic code modification unless explicitly requested.
- Prioritise security and type issues.
- Every issue must include a concrete fix suggestion.
- Do not comment on style unless a linter config is present.

Validation run

# User input
"帮我review一下src/api/目录的代码"
# Claude execution trace
1. Detects tsconfig.json → TypeScript project.
2. Detects .eslintrc.json → ESLint configured.
3. Glob "src/api/**/*.{ts,tsx}" → reads files.
4. Applies TypeScript review rules per file.
5. Generates graded report.
# Sample output
## Review Report
### Critical (2)
[Security] src/api/auth.ts:23 – SQL string concatenation enables injection.
  Impact: attacker can read/modify DB.
  Suggestion: use parameterised queries.
[Type] src/api/user.ts:45 – findUser may return undefined.
  Impact: runtime error when accessed.
  Suggestion: add null check `if (!user) return null`.
### Warning (3)
…
### Statistics
- Files reviewed: 6
- Critical: 2
- Warning: 3
- Suggestion: 5
- Quality score: 7/10

Golden Rules Summary

Place trigger phrases in the first 250 characters of description.

Use progressive loading – keep heavy data in Level 3 external files.

Define clear boundaries: what the Skill does and does not do.

Write from the user’s perspective; reverse‑engineer natural language triggers.

Keep each Skill focused on a single responsibility.