This skill teaches the foundational structure of a well-formed skill file for SkillDB. A skill file is a markdown document that teaches an AI agent how to perform a specific task or apply domain knowledge. Understanding the anatomy of a skill file is essential for creating skills that are discoverable, effective, and maintainable.

## Key Points

- Encodes expert knowledge in a format AI agents can consume
- Provides actionable instructions, not just reference material
- Includes enough context for the agent to know when and how to apply the skill
- Is discoverable through metadata (tags, title, category)
- [Specific scenario 1]
- [Specific scenario 2]
- [Specific scenario 3]
- [Scenario where a different skill is more appropriate]
- [Scenario where this approach doesn't apply]
1. Identify natural boundaries (e.g., "setup" vs. "usage" vs. "debugging")
2. Create a parent skill with overview + links to children
3. Each child skill stands alone (doesn't require reading parent first)

## Quick Example

```
Skill File = Domain Knowledge + Structured Format + Agent Instructions
```

```
Code Block Rules:
├── Always specify language for syntax highlighting
│   └──
```

Skill File Structure and Anatomy

Purpose

This skill teaches the foundational structure of a well-formed skill file for SkillDB. A skill file is a markdown document that teaches an AI agent how to perform a specific task or apply domain knowledge. Understanding the anatomy of a skill file is essential for creating skills that are discoverable, effective, and maintainable.

What Is a Skill File?

A skill file is a structured markdown document that:

• Encodes expert knowledge in a format AI agents can consume
• Provides actionable instructions, not just reference material
• Includes enough context for the agent to know when and how to apply the skill
• Is discoverable through metadata (tags, title, category)

Skill File = Domain Knowledge + Structured Format + Agent Instructions

The key distinction from documentation: documentation explains how things work for humans. Skill files instruct AI agents on how to perform tasks.

Required Structure

Frontmatter

Every skill file begins with YAML frontmatter enclosed in --- delimiters:

---
title: "Clear, Descriptive Title"
category: "category-name"
tags: ["tag1", "tag2", "tag3"]
version: "1.0.0"
---

Frontmatter fields explained:

title (required):
├── Clear, specific description of what the skill covers
├── Should be searchable — users will find by title
├── Include key technology/domain terms
├── Examples:
│   ├── GOOD: "React Server Components with Next.js App Router"
│   ├── GOOD: "PostgreSQL Query Optimization for Large Tables"
│   ├── BAD: "React Stuff" (too vague)
│   ├── BAD: "How to Use the Database" (too generic)
│   └── BAD: "Advanced Techniques" (says nothing)

category (required):
├── Groups related skills into packs
├── Use kebab-case: "react-skills", "devops-skills"
├── Should match directory name
└── One category per skill

tags (required):
├── Array of relevant keywords for discovery
├── Include: technology names, concepts, use cases
├── 3-8 tags recommended
├── Tags improve search and recommendation
├── Example: ["react", "server-components", "ssr", "nextjs", "performance"]

version (required):
├── Semantic versioning: MAJOR.MINOR.PATCH
├── Start at "1.0.0"
├── Increment MINOR for content additions
├── Increment MAJOR for structural changes
└── Increment PATCH for fixes and clarifications

Main Title and Purpose

Immediately after frontmatter:

# Skill Title (matches frontmatter title)

## Purpose

A 2-4 sentence description of what this skill enables.
What task does it help accomplish? What problem does it solve?
Who benefits from this skill?

The Purpose section serves as an executive summary. An AI agent reads this to decide whether this skill is relevant to the current task.

Purpose writing guidelines:

DO:
├── State what the skill enables ("This skill covers building...")
├── Specify the domain or technology
├── Mention the target outcome
└── Be specific enough that relevance is clear

DON'T:
├── Write a lengthy introduction
├── Include background history
├── Start with "In this skill we will..."
└── Be so vague it could apply to anything

Core Content Sections

The body of the skill uses standard markdown with specific section patterns:

Recommended Sections (adapt to your skill):
├── ## Core Concepts        — Foundational knowledge needed
├── ## Implementation       — How to do the thing
├── ## Patterns             — Common approaches and templates
├── ## Examples             — Concrete, working examples
├── ## Common Pitfalls      — What goes wrong and why
├── ## Performance          — Optimization considerations
├── ## Testing              — How to verify correctness
└── ## When to Apply        — Decision framework for using this skill

Section Depth Guidelines

Section Structure Rules:
├── Use ## for major sections (never # except title)
├── Use ### for subsections within major sections
├── Use #### sparingly (max depth in most skills)
├── Never go deeper than #### (hard to navigate)
├── Each major section should be 30-100 lines
├── Each subsection should be 10-40 lines
└── If a subsection exceeds 50 lines, consider splitting

The "When to Apply" Section

Every skill file should end with guidance on when to use it:

## When to Apply This Skill

Use this skill when:
- [Specific scenario 1]
- [Specific scenario 2]
- [Specific scenario 3]

Do not use this skill when:
- [Scenario where a different skill is more appropriate]
- [Scenario where this approach doesn't apply]

This section is critical for AI agents making skill selection decisions.

Content Guidelines

Code Blocks

Code Block Rules:
├── Always specify language for syntax highlighting
│   └── ```python, ```typescript, ```sql, etc.
├── Include only runnable/realistic code
├── Add comments explaining non-obvious lines
├── Keep blocks focused (20-50 lines max)
├── If longer code is needed, break into multiple blocks with explanation
├── Use ... or # ... to indicate omitted standard code
└── Never include placeholder/lorem-ipsum code without noting it

Example of good code block:
```python
# Configure connection pooling for high-traffic PostgreSQL
import psycopg2.pool

pool = psycopg2.pool.ThreadedConnectionPool(
    minconn=5,         # Minimum idle connections
    maxconn=20,        # Maximum total connections
    host="localhost",
    database="mydb",
    user="app_user",
    # Use environment variable for password, never hardcode
    password=os.environ["DB_PASSWORD"],
)

### ASCII Diagrams and Tables

ASCII diagrams are preferred over descriptions for architectural and structural content:

Diagram Guidelines: ├── Use box-drawing characters for clean diagrams │ └── ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ │ ─ ╭ ╮ ╯ ╰ ├── Use tree notation for hierarchies │ └── ├── for branches, └── for last item ├── Use tables for comparison data │ └── ┌───┬───┐ format with proper alignment ├── Keep diagrams under 60 characters wide (readability) └── Always add a label or description near the diagram

### Tone and Voice

Writing Style for Skill Files: ├── Authoritative but approachable ├── Direct and actionable ("Do X" not "You might want to consider X") ├── Technical precision (correct terminology, accurate details) ├── Concise (say it once, clearly) ├── Practical over theoretical (show, don't just tell) └── Second person when instructing ("Use this when..." not "One should...")

Avoid: ├── Marketing language ("revolutionary", "game-changing") ├── Hedging ("maybe", "perhaps", "it depends" without specifying on what) ├── Filler phrases ("It's important to note that...") ├── Opinions presented as facts (unless widely accepted best practice) └── References that will become outdated (specific version numbers as current)

## Length and Scope

### Ideal Skill File Size

Size Guidelines: ├── Minimum: 100 lines (enough to be useful) ├── Target: 200-400 lines (thorough but focused) ├── Maximum: 600 lines (beyond this, split into multiple skills) └── Exception: Reference/lookup skills can be shorter (lists, tables)

Scope Rules: ├── One skill = one coherent topic ├── If you need two "Purpose" statements, it's two skills ├── If reading the skill takes > 10 minutes, it's too broad ├── Better to have 3 focused skills than 1 sprawling one └── Cross-reference related skills rather than duplicating content

### Splitting Large Topics

When a topic is too big for one skill:

1. Identify natural boundaries (e.g., "setup" vs. "usage" vs. "debugging")
2. Create a parent skill with overview + links to children
3. Each child skill stands alone (doesn't require reading parent first)
4. Share common frontmatter category and related tags

Example: ├── kubernetes-fundamentals.md (overview, when to use K8s) ├── kubernetes-deployment.md (creating and managing deployments) ├── kubernetes-networking.md (services, ingress, network policies) ├── kubernetes-storage.md (volumes, PVCs, storage classes) └── kubernetes-troubleshooting.md (debugging pods, logs, events)

## Template

Here is a complete template for a new skill file:

```markdown
---
title: "Technology/Task: Specific Aspect"
category: "category-name"
tags: ["tech", "aspect", "use-case"]
version: "1.0.0"
---

# Technology/Task: Specific Aspect

## Purpose

[2-4 sentences: What does this skill enable? What problem does it solve?]

## Core Concepts

### [Concept 1]

[Explanation with examples]

### [Concept 2]

[Explanation with examples]

## Implementation

### [Step or Approach 1]

[Detailed instructions with code]

### [Step or Approach 2]

[Detailed instructions with code]

## Common Pitfalls

[List of mistakes and how to avoid them]

## When to Apply This Skill

Use this skill when:
- [Scenario 1]
- [Scenario 2]

Do not use this skill when:
- [Alternative scenario]

Validation Checklist

Before publishing a skill file, verify:

□ Frontmatter is valid YAML (title, category, tags, version)
□ Title is specific and searchable
□ Purpose section clearly states what the skill enables
□ Content is actionable (instructions, not just information)
□ Code examples are correct and runnable
□ ASCII diagrams render correctly in fixed-width font
□ "When to Apply" section helps with skill selection
□ Length is 100-600 lines
□ Scope is focused on one coherent topic
□ No broken markdown formatting
□ Tags are relevant and useful for discovery
□ Technical content is accurate and current

When to Apply This Skill

Use this skill when:

• Creating your first skill file
• Reviewing a skill file for structural completeness
• Establishing templates for a team creating skills
• Converting documentation into skill file format
• Evaluating whether a skill file meets quality standards