Skill files are consumed by AI agents (LLMs) as context for task execution. Writing for an AI agent differs from writing for humans: agents have specific strengths (following precise instructions, handling structured data) and limitations (context window size, tendency to hallucinate when uncertain). This skill covers how to write skill files that AI agents can parse, understand, and execute reliably.

## Key Points

1. User provides a task
2. Agent searches skill database
3. Agent selects relevant skill(s) based on metadata + Purpose
4. Agent loads skill content into context
5. Agent interprets instructions
6. Agent executes task guided by skill
7. Agent verifies result against skill criteria
- CREATE INDEX idx_users_email ON users(email);
- CREATE INDEX idx_orders_user_id ON orders(user_id);
- CREATE INDEX idx_orders_created_at ON orders(created_at DESC);"
1. Input is null or undefined → return empty array
2. Input array is empty → return empty array

## Quick Example

```

```

```
For AI Agent consumption:

1. Always include the language identifier:
```

Writing Skills for AI Agent Consumption

Purpose

Skill files are consumed by AI agents (LLMs) as context for task execution. Writing for an AI agent differs from writing for humans: agents have specific strengths (following precise instructions, handling structured data) and limitations (context window size, tendency to hallucinate when uncertain). This skill covers how to write skill files that AI agents can parse, understand, and execute reliably.

How AI Agents Consume Skills

The Agent Workflow

Agent Skill Consumption:
1. User provides a task
2. Agent searches skill database
3. Agent selects relevant skill(s) based on metadata + Purpose
4. Agent loads skill content into context
5. Agent interprets instructions
6. Agent executes task guided by skill
7. Agent verifies result against skill criteria

Context Window Reality:
├── Total context: 100K-1M+ tokens (varies by model)
├── Skill file: 500-3000 tokens typically
├── User task: 50-500 tokens
├── Code context: 1000-50000 tokens
├── Remaining: For agent reasoning and output
└── Key insight: Skills compete for context space with everything else

Agent Strengths to Leverage

AI agents are GOOD at:
├── Following explicit, step-by-step procedures
├── Pattern matching (applying templates to new contexts)
├── Handling structured data (JSON, YAML, tables)
├── Maintaining consistency within a task
├── Processing checklists and validation criteria
├── Applying rules across many instances
└── Code generation from clear specifications

AI agents are POOR at:
├── Reading between the lines (implication, subtext)
├── Recovering from ambiguity (picks one interpretation, may be wrong)
├── Knowing when to stop (may over-apply skill)
├── Judging relevance without explicit criteria
├── Handling contradictions (follows most recent instruction)
├── Real-world verification (can't test code)
└── Understanding humor, sarcasm, or cultural references

Writing Principles for Agents

Principle 1: Be Explicit Over Implicit

IMPLICIT (human can infer, agent may not):
"Set up the database with appropriate indexes."

EXPLICIT (agent knows exactly what to do):
"Create a PostgreSQL database named 'appdb'.
Add the following indexes:
- CREATE INDEX idx_users_email ON users(email);
- CREATE INDEX idx_orders_user_id ON orders(user_id);
- CREATE INDEX idx_orders_created_at ON orders(created_at DESC);"

IMPLICIT:
"Handle the edge cases."

EXPLICIT:
"Handle these edge cases:
1. Input is null or undefined → return empty array
2. Input array is empty → return empty array
3. Input contains duplicates → deduplicate before processing
4. Input exceeds 1000 items → process in batches of 100"

Principle 2: Use Structured Formats

Agents parse structured data more reliably than prose.

PROSE (harder to parse):
"The configuration should set the port to 3000, enable CORS
for the frontend domain, set the database connection timeout
to 5 seconds, and log at the info level in production but
debug level in development."

STRUCTURED (easier to parse):
Configuration:
- PORT: 3000
- CORS_ORIGIN: "https://app.example.com"
- DB_TIMEOUT: 5000 (milliseconds)
- LOG_LEVEL:
  - production: "info"
  - development: "debug"

Or as a code block:
```json
{
  "port": 3000,
  "cors": { "origin": "https://app.example.com" },
  "database": { "timeout": 5000 },
  "logging": {
    "level": "${NODE_ENV === 'production' ? 'info' : 'debug'}"
  }
}

### Principle 3: Provide Decision Criteria

Agents need explicit criteria to make decisions.

WITHOUT CRITERIA (agent guesses): "Choose the right data structure."

WITH CRITERIA (agent can decide): "Select data structure based on access pattern:

• If lookups by key dominate → use HashMap
• If ordered iteration needed → use BTreeMap
• If frequent insertions/deletions at both ends → use VecDeque
• If random access by index needed → use Vec
• If uniqueness required → use HashSet"

WITHOUT CRITERIA: "Optimize the function if it's slow."

WITH CRITERIA: "Optimize if function execution time exceeds 100ms for typical input sizes (100-1000 items). Optimization priority:

1. Reduce algorithmic complexity (O(n^2) → O(n log n))
2. Eliminate redundant computations (cache/memoize)
3. Reduce allocations (reuse buffers)
4. Parallelize if > 10,000 items"

### Principle 4: Scope Boundaries

Tell the agent when NOT to apply the skill.

OUT OF SCOPE declarations: "This skill does NOT cover:

• Database schema design (see 'Database Schema Design' skill)
• ORM selection (see 'ORM Comparison' skill)
• Database hosting/deployment (see 'Database Operations' skill)

Stop applying this skill when:

• The query is already performing within acceptable limits
• The table has fewer than 10,000 rows (optimization unnecessary)
• The application is in prototype/MVP phase (premature optimization)"

WHY this matters: ├── Without boundaries, agents may over-apply skills ├── Agent might optimize a function that doesn't need optimizing ├── Agent might add complexity beyond what the task requires └── Clear boundaries prevent skill misapplication

### Principle 5: Token Efficiency

Context window space is valuable. Be concise.

WASTEFUL (adds tokens without adding information): "It's important to note that when working with databases, one of the key considerations that developers often overlook is the importance of proper indexing. Indexing, as many experienced developers will tell you, can make a significant difference in query performance."

EFFICIENT (same information, fewer tokens): "Add indexes to frequently queried columns. Without indexes, queries perform full table scans — O(n) instead of O(log n)."

Token Optimization Strategies: ├── Cut filler phrases: "It's worth noting that" → just state the fact ├── Use lists over paragraphs for sets of items ├── Use tables over paragraphs for comparisons ├── Use code blocks over text descriptions of code ├── Remove redundant examples (one clear example > three mediocre ones) └── Front-load critical information (agent may hit context limits)

Content Priority (most important first):

1. Purpose statement (what this skill does)
2. Core instructions (how to do it)
3. Decision criteria (when to do what)
4. Examples (concrete application)
5. Edge cases and warnings
6. Background context (why this approach)

### Principle 6: Consistent Terminology

Agents treat different terms as different concepts.

INCONSISTENT (agent may treat as different things): "Create a component... Build the widget... Implement the module..." (Are these the same thing? Agent may create three separate things.)

CONSISTENT (agent knows it's the same thing): "Create a UserProfile component... The UserProfile component should... Configure the UserProfile component..."

Terminology Rules: ├── Choose one term per concept and use it throughout ├── If introducing an abbreviation, define it once: │ "Continuous Integration (CI) runs tests on every push. │ CI pipelines should complete within 10 minutes." ├── Use the same term the user likely uses ├── Match technology-specific naming conventions │ (React: "component"; Vue: "component"; Angular: "component") └── If a concept has multiple valid names, choose one and note others: "Use a HashMap (also known as dictionary or hash table)."

## Formatting for Agent Parsing

### Markdown Conventions

Agent-Friendly Markdown: ├── Use headings for navigation (agents use them as section markers) ├── Use code blocks for anything the agent should reproduce exactly ├── Use bullet lists for unordered sets of items ├── Use numbered lists for ordered procedures ├── Use tables for structured comparisons ├── Use bold for key terms being defined ├── Use inline code for specific names: functionName, fileName.ts └── Avoid: ├── Inline HTML (some agents parse this differently) ├── Deeply nested lists (> 3 levels = confusing) ├── Extremely wide tables (may wrap unpredictably) └── Footnotes or endnotes (agents may miss the reference)

### Code Block Best Practices

For AI Agent consumption:

1. Always include the language identifier: typescript (not just )

2. Include necessary imports:

   import { useState, useEffect } from 'react';
   // Don't assume the agent knows which imports are needed
   

3. Show the complete function, not just the relevant line:

   // GOOD: Complete, copyable function
   export function validateEmail(email: string): boolean {
     const pattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
     return pattern.test(email);
   }
   

4. Mark sections that should be customized:

   const config = {
     apiUrl: 'YOUR_API_URL_HERE',    // <-- Replace with actual URL
     apiKey: process.env.API_KEY,     // <-- Set in environment
     timeout: 5000,                   // <-- Adjust as needed
   };
   

5. Include expected output in comments:

   npm run build
   # Expected output:
   # > app@1.0.0 build
   # > tsc && vite build
   # ✓ built in 1.23s
   

## Common Agent Interpretation Issues

Issue: Agent follows skill too literally Example: Skill says "add an index on email column" Agent adds index even when table doesn't have an email column Fix: Add conditional: "If the table has an email column, add an index on it"

Issue: Agent applies skill out of context Example: Performance optimization skill applied to prototype code Fix: Add scope: "Apply only when performance is a stated requirement"

Issue: Agent combines conflicting instructions Example: Two skills give different advice on error handling Fix: Add specificity: "For API endpoints, use this pattern. For background jobs, use [other skill]'s pattern."

Issue: Agent misses nuance in prose Example: "Generally, you should use connection pooling, but for serverless functions you may want per-request connections" Agent always uses connection pooling. Fix: Make conditional explicit with clear criterion: "If deployment target is serverless (Lambda, Cloud Functions): Use per-request connections. If deployment target is long-running server: Use connection pooling."

## Testing Agent Comprehension

Agent Comprehension Test Protocol:

1. Give agent ONLY the skill file (no additional context)
2. Ask: "Summarize what this skill teaches in 3 bullet points" → Verifies agent understands the content
3. Ask: "Given [specific scenario], how would you apply this skill?" → Verifies agent can map skill to real tasks
4. Ask: "When should you NOT use this skill?" → Verifies agent understands scope boundaries
5. Give a task and evaluate execution → Verifies end-to-end skill effectiveness

Red Flags: ├── Agent summarizes differently than intended → Purpose is unclear ├── Agent applies skill to wrong scenario → Scope boundaries missing ├── Agent follows instructions in wrong order → Sequencing is ambiguous ├── Agent adds steps not in the skill → Instructions are incomplete └── Agent skips steps → Steps may be unclear or seem optional

## When to Apply This Skill

Use this skill when:
- Writing skill files that will be consumed by AI agents
- Optimizing existing skills for better agent comprehension
- Debugging cases where agents misinterpret skill instructions
- Deciding on formatting and structure for agent-friendly content
- Reducing skill file token count without losing information
- Establishing writing guidelines for a team creating agent-facing skills