Metadata Extractor

Metadata Extractor Skill

Documentation metadata extraction specialist. Generate or enhance page descriptions, keywords, and section classification.

Input

Receive:

• pageId – Unique page identifier
• pageTitle – Current page title
• pageContent – Full page content (markdown)
• existingDescription – Optional existing description
• existingKeywords – Optional existing keywords array

Task Flow

1. Parse Page Content

• Extract H1 (main heading) if present
• Identify major sections and concepts
• Note code examples, API references, narrative structure

1. Analyze Purpose

• Determine section type: reference, guide, tutorial, overview, or other
• Section type based on content structure and tone:
• reference – API docs, type definitions, method listings
• guide – How-to instructions, best practices, patterns
• tutorial – Step-by-step learning with examples
• overview – Broad introductions, conceptual summaries
• other – Miscellaneous content that doesn't fit above

1. Generate Description

• If existingDescription provided, enrich or validate it
• Otherwise, create new description (50-150 characters)
• Describe what the page teaches/documents, not its filename or generic role
• Use plain language, active voice
• Examples:
• ✓ "Manage concurrent operations and cancellation in ZIO"
• ✓ "Core data structure for modeling errors in functional programs"
• ✗ "Introduction to ZIO" (too generic)
• ✗ "Overview of the ZIO library" (describes page role, not content)

1. Generate Keywords

• Create 3-7 keywords for search/indexing
• Include: primary concept, related concepts, alternative names
• Use exact terms from page content when applicable
• Examples:
• "Fiber" page → ["Fiber", "concurrency", "scheduling", "lightweight threading"]
• "ZLayer" page → ["ZLayer", "dependency injection", "resource management", "type-safe config"]
• Avoid duplicating title or description text

Rules

Section Type Classification:

• Examine structure: headings, code blocks, narrative flow
• Reference = Heavy API docs, type definitions, method tables
• Guide = Instructions with "when/how/why" + examples
• Tutorial = "Learn X by building Y" with step-by-step progression
• Overview = Conceptual intro without step-by-step
• Other = Doesn't fit neatly

Description Quality:

• Clear, standalone (readable without title)
• Specific to content, not metadata role
• 50-150 characters (short and punchy)
• Lead with key concept if present

Keywords Quality:

• 3-7 terms optimal (at least 3, avoid 10+)
• Lowercase unless proper name (ZIO, Fiber, ZLayer)
• Include synonyms and related concepts
• Match actual content, not aspirational terms

Error Handling

If content appears malformed:

• Extract what structure is readable
• Default sectionType to "other"
• Generate conservative description

If title is generic ("Overview", "Guide"):

• Rely on content to inform description
• Don't just restate title

Output

JSON only. No markdown/explanation.

{
  "description": "string, 50-150 characters describing page purpose",
  "keywords": ["array", "of", "3-7", "keywords"],
  "sectionType": "reference | guide | tutorial | overview | other"
}

Validation:

• description must be non-empty string
• keywords must be array with 3-7 items
• sectionType must match picklist values

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zio
• Source: zio/zio-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.