docs-organize-types - SKILL.md Agent Skill

name: docs-organize-types description: Organize related ZIO Blocks data types into logical categories within sidebars.js. Use this skill to group data types by functionality (e.g., "Collections", "Type System", "Resource Management", "DI & Configuration"). Supports manual categorization (specify types and category) or automatic analysis (scan docs/reference/ and suggest intelligent groupings). The skill updates sidebars.js while preserving existing structure, maintains alphabetical order, and verifies syntax validity. allowed-tools: Glob, Grep, Read, Edit, Bash

Organize Data Types in Sidebars

Improve documentation structure by organizing related ZIO Blocks data types into meaningful categories.

Two Modes of Operation

Mode 1: Manual Categorization

When you know exactly which types should go into a category.

Invocation:

docs-organize-types [type1] [type2] [type3] --category "[Category Name]"

Example:

docs-organize-types chunk list vector --category "Collections"

This moves (or creates links for) chunk, list, and vector into a "Collections" category.

Mode 2: Automatic Categorization

When you want the skill to analyze all data types and suggest intelligent groupings.

Invocation:

docs-organize-types --auto

The skill will:

Scan docs/reference/ for all data type documentation files
Extract type signatures, descriptions, and relationships
Analyze integration patterns (which types depend on others)
Group types by functional area:
- Collections: Chunk, List, Vector, etc.
- Type System: TypeId, Schema, DynamicValue, etc.
- Resource Management: Resource, Scope, Wire, etc.
- Context & DI: Context, Wire, etc.
- Error Handling: SchemaError, Validation, etc.
- Utilities: MediaType, Syntax, Docs, etc.
Suggest category assignments with confidence levels
Preview the new sidebars.js structure

Workflow: Manual Mode

Step 1: Validate Input

Verify each type has a corresponding .md file in docs/reference/
Confirm the category name is reasonable (avoid duplicates with existing categories)
If any type is missing, report and stop

Step 2: Check Existing Structure

Read docs/sidebars.js
Identify the Reference section
Check if the category already exists; if so, note its current contents

Step 3: Create/Update Category index.md

Create a new file docs/reference/[category-kebab-case]/index.md with:

---
id: [category-kebab-case]
title: "[Category Name]"
---

## Introduction

[2-3 sentences explaining the category and its purpose]

**Related Types:**
- [`TypeName1`](./<type1>.md) — brief description
- [`TypeName2`](./<type2>.md) — brief description
- [`TypeName3`](./<type3>.md) — brief description

## Overview

[Additional context about how these types work together and when to use them as a group]

Extract descriptions from each type's .md file (first sentence after the opening definition).

Step 4: Update sidebars.js

If the category doesn't exist, create it:

{
  type: "category",
  label: "[Category Name]",
  link: { type: "doc", id: "reference/[category-kebab-case]/index" },
  items: [
    "reference/[category-kebab-case]/[type1]",
    "reference/[category-kebab-case]/[type2]",
    "reference/[category-kebab-case]/[type3]"
  ]
}

If it does exist, append new types in alphabetical order.

Maintain alphabetical order of categories within the Reference section.

Note: Update item paths to include the category subdirectory: "reference/[category-kebab-case]/[type-id]"

Step 5: Verify Syntax

Parse the updated sidebars.js with Node.js to ensure valid JavaScript syntax:

node -c docs/sidebars.js

If there are errors, report and revert.

Step 6: Report Changes

Show:

Added Category: Yes/No (new category created)
Index File Created: path to new index.md
Types Added: list of types moved into the category
Verification: ✅ Syntax valid | ❌ Syntax error (reverted)
Preview: before/after snippet of the Reference section

Workflow: Automatic Mode

Step 1: Scan Documentation

Use Glob to find all .md files in docs/reference/:

glob("docs/reference/*.md")

Extract the id from each file's frontmatter (line 2, id: <name>).

Step 2: Analyze Type Relationships

For each type file:

Read the file to extract:

Title (frontmatter title:)
Definition (opening 1-3 sentences)
Key features (bullet points, if present)
Mentions of other types (grep for references: [TypeName](./type-name.md))

Build a relationship graph: if Type A mentions Type B, record that edge.

Step 3: Propose Categories

Based on type names, descriptions, and relationships, assign each type to a category:

Collection Types → Chunk, List, Vector, NonEmptyList, etc.

Signal: type name contains "chunk" | "list" | "vector" | "sequence" | "collection"
Context: used for organizing/storing data

Type System & Schemas → Schema, TypeId, DynamicValue, SchemaError, etc.

Signal: type name contains "schema" | "type" | "dynamic" | "error" | "validation"
Context: used for type representation, validation, transformation

Resource Management & DI → Resource, Scope, Wire, Finalizer, etc.

Signal: type name contains "resource" | "scope" | "wire" | "finalizer" | "context"
Context: used for lifecycle management, dependency injection

Error & Validation → SchemaError, Validation, etc.

Signal: type name or content mentions error handling, constraints
Context: used for error representation and validation

Utilities & Formats → MediaType, Syntax, Docs, JSON, XML, etc.

Signal: type name is format/utility name (not a core abstraction)
Context: add-on functionality, specific formats

For each proposed grouping, compute a confidence level:

High (90%+): Clear semantic signal (name + description alignment)
Medium (70-89%): Some signal (description or relationships align)
Low (<70%): Weak signal (consider alternatives)

Step 4: Preview Proposed Structure

Show the user:

Proposed Categories with types grouped and confidence levels
Before/After snippet of sidebars.js
Unassigned Types (if any) — types that don't fit well in any category

Step 5: User Confirmation

Wait for user input:

Accept All: Apply all proposed categories
Selective: Accept specific categories only
Reject: Keep current flat structure

Step 6: Create Category index.md Files

For each approved category, create docs/reference/[category-kebab-case]/index.md with:

Category title and introduction
List of related types with brief descriptions
Overview section explaining how types work together

Use the analysis from Step 2 (descriptions and relationships) to write the introduction.

Step 7: Update sidebars.js

Once approved, update sidebars.js with the new structure, maintaining:

Alphabetical order of categories
Alphabetical order of types within each category
Link to category index.md file in category definition
Existing non-categorized types (if kept)

Step 8: Verify & Report

Same as manual mode: verify syntax, report changes including index.md file creation.

Output Format

Summary Report (displayed to user):

✅ Categorization Complete

Added Categories: [N]
- [Category 1]: [type1], [type2], [type3]
- [Category 2]: [type4], [type5]

Modified Categories: [N]
- [Category]: added [type6]

Verification: ✅ Syntax valid

Preview:
  Reference
    ├─ [Category 1]
    │  ├─ chunk
    │  ├─ list
    │  └─ vector
    ├─ [Category 2]
    │  ├─ schema
    │  └─ typeid
    └─ [Uncategorized] (if any)
       └─ mediatype

Implementation Notes

Directory Structure: Each category creates a subdirectory: docs/reference/[category-kebab-case]/
- Category index: docs/reference/[category-kebab-case]/index.md
- Type files are organized within the category directory (may involve moving existing files or creating symlinks)
Index.md Content:
- Frontmatter with id matching the category kebab-case name
- Introduction section explaining the category
- List of related types with descriptions
- Overview of how types work together
Sidebar Paths: Updated to reflect category structure: "reference/[category-kebab-case]/[type-id]"
Category Link: Sidebar category definition includes link: { type: "doc", id: "reference/[category-kebab-case]/index" }
Alphabetical order is maintained within each category and at the category level
Existing categories are preserved if they already exist in sidebars.js
Syntax validation is mandatory — invalid changes are reverted
No breaking changes — existing structure is preserved; only new categories are added