Documentation Clarity

By the end of this lesson, you'll understand the five documentation elements every skill needs — and why documentation isn't just for humans; it's what the LLM uses to decide whether to invoke your skill.

The Dual Audience Problem

Skill documentation serves two audiences simultaneously:

1. Humans who maintain, review, and compose skills
2. LLMs that dynamically select tools at runtime based on descriptions

This is unique. Traditional API documentation only needs to be readable by humans. But in agentic systems, the LLM reads your skill's description and decides whether to invoke it. Vague descriptions lead to hallucinated invocations or missed opportunities.

The Prompt Engineering Guide research emphasizes: clear documentation improves both human understanding and LLM interpretation of when and how to use skills.

The Five Documentation Elements

1. Description (Purpose Statement)

One to two sentences. What the skill does — not how it works internally.

# Good — specific, actionable
description: "Analyzes CSV datasets to identify statistical anomalies
  and generates a summary report with confidence scores."

# Bad — vague, no clear invocation signal
description: "Helps with data stuff."

2. Usage Triggers

Explicit conditions for when the skill should be activated. This is the decision boundary.

triggers:
  - "User asks to analyze a CSV or tabular dataset"
  - "User requests anomaly detection on numeric data"
  - "User wants statistical summary of a data source"
not_triggers:
  - "User asks to visualize data (use chart-skill instead)"
  - "User asks about database queries (use sql-skill instead)"

3. Examples

Representative input/output pairs including edge cases. These serve as few-shot examples for the LLM and as test fixtures for validation.

examples:
  - input: { data_source: "sales_q4.csv", analysis_type: "anomaly" }
    output: { result: "3 anomalies detected in revenue column...", confidence: 0.92 }
    explanation: "Standard anomaly detection on numeric columns"
  - input: { data_source: "empty.csv", analysis_type: "summary" }
    output: { result: "No data available for analysis", confidence: 0.0 }
    explanation: "Edge case — empty file returns gracefully"

4. Limitations

Explicit boundaries. What the skill cannot do. This prevents the LLM from over-promising.

limitations:
  - "Maximum file size: 100MB"
  - "Only supports CSV and TSV formats (not Excel or Parquet)"
  - "Does not perform causal inference — correlation only"
  - "Requires at least 30 rows for statistical significance"

5. Dependencies

Required tools, APIs, or external services. Critical for governance and deployment planning.

dependencies:
  tools: ["file_reader", "statistics_engine"]
  apis: ["internal-data-lake-v2"]
  services: ["Amazon S3 (for large file staging)"]

The Registry Connection

The governance guide stresses that documentation is the foundation of discoverability. In enterprise deployments with hundreds of agents, registries use these five elements for:

• Discovery — teams find existing skills instead of duplicating effort
• Quality gates — skills without clear limitations fail governance review
• Impact assessment — dependency lists enable blast-radius analysis during changes

Verify Your Understanding

Apply It

Open one of your Kiro skills (check ~/.kiro/skills/) and evaluate its documentation against the five elements. Score it:

• ☐ Description — specific enough for tool selection?
• ☐ Triggers — does it define when to fire and when not to?
• ☐ Examples — includes at least one edge case?
• ☐ Limitations — explicit about what it can't do?
• ☐ Dependencies — lists all external requirements?