AI Context Writer Skill

Use this skill when creating or updating ai-context.md files that document modules in the codebase. These files are indexed by the context-crawler and surfaced via /modules, /module, and /module-search commands.

File Location

Context files must be named exactly ai-context.md and placed at the root of the module:

packages/my-package/ai-context.md    # Internal module
apps/my-app/ai-context.md            # Internal module
.context/external-lib/ai-context.md  # External reference (submodule)

Required Structure

Frontmatter (YAML)

---
path: packages/my-package
summary: One-line description mentioning purpose and key technologies
tags: [effect, http-client, sdk-wrapper]
---

Frontmatter Fields:

• path - Module identifier (relative path from repo root)
• summary - Single sentence, concise description for module listings
• tags - Optional categorization for search (technologies, domains)

Markdown Body Sections

# Module Name

High-level overview paragraph explaining the module's purpose.

## Architecture

┌──────────────────┐
│    Component     │
└──────────────────┘
        │
        ▼
┌──────────────────┐
│     Service      │
└──────────────────┘

Brief explanation of the architecture diagram.

## Core Modules

| Module | Purpose |
|--------|---------|
| `Service.ts` | Main service implementation |
| `Client.ts` | HTTP client wrapper |

## Usage Patterns

### Basic Usage

```typescript
import * as MyModule from "@/packages/my-package"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const service = yield* MyModule.Service
  return yield* service.doThing()
})

Key Patterns

Pattern Name

Description of when and why to use this pattern.

// Example code

Design Decisions

AD-1: Decision Title Explanation of the decision and trade-offs.

AD-2: Another Decision Why this approach was chosen over alternatives.

Dependencies

• effect - Core Effect library
• @effect/platform - Platform abstractions

Spec Reference

• specs/my-feature/DESIGN.md

## Section Guidelines

### Architecture Diagram

Use simple ASCII box-and-arrow diagrams:

┌──────────────┐ ┌──────────────┐ │ Service │────▶│ Client │ └──────────────┘ └──────────────┘ │ ▼ ┌──────────────┐ │ Repository │ └──────────────┘

Characters: `┌ ┐ └ ┘ │ ─ ▼ ▲ ◀ ▶ ────▶`

### Core Modules Table

Quick reference for key files:

```markdown
| Module | Purpose |
|--------|---------|
| `ParallelClient.ts` | HTTP client with Effect integration |
| `ParallelRun.ts` | Async task execution |
| `Errors.ts` | Tagged error types |

Usage Patterns

Always include:

• Full imports with namespace pattern (import * as X)
• Effect.gen for effectful code
• Layer construction if services are involved

import * as MyService from "@/packages/my-service"
import { Effect, Layer } from "effect"

const program = Effect.gen(function* () {
  const svc = yield* MyService.Service
  return yield* svc.operation()
})

const live = program.pipe(
  Effect.provide(MyService.Live)
)

Design Decisions

Use AD-N format for traceability:

**AD-1: Use Effect.gen over flatMap chains**
Effect.gen provides cleaner syntax and better stack traces. The generator pattern
makes sequential operations readable without callback nesting.

**AD-2: Schema.TaggedStruct for all domain types**
Automatic discriminator and Data equality support. Enables pattern matching
with Match.typeTags.

Dependencies

List external packages the module depends on:

## Dependencies

- `effect` - Core Effect types and functions
- `@effect/platform` - FileSystem, HttpClient, Terminal
- `@effect/schema` - Runtime validation and serialization

Summary Writing

The summary is critical - it appears in /modules listings.

Good summaries:

• "Effect wrapper for Parallel AI SDK - web search, content extraction, and async task runs"
• "React frontend with Effect-Atom state management and TanStack Router"
• "SQLite-backed workflow engine for durable execution patterns"

Bad summaries:

• "A module for doing stuff" (too vague)
• "This is the main package that handles various functionality" (no specifics)

Summary formula: [Primary purpose] - [key feature 1], [key feature 2], and [key feature 3]

Discovery and Indexing

Context files are indexed by context-crawler.ts:

1. Recursively finds all ai-context.md files
2. Extracts frontmatter (path, summary, tags)
3. Falls back to first paragraph if no summary
4. Excludes node_modules, .git, dist, build, .turbo

Module Classification

• Internal: Local ai-context.md files in packages/apps
• External: Submodules from .gitmodules (may lack ai-context.md)

External modules without context files show: (grep for implementation details)

Commands for Discovery

# List all modules with summaries
/modules

# Get full content of specific module
/module packages/parallel

# Search modules by pattern
/module-search http

Complete Example

---
path: packages/parallel
summary: Effect wrapper for Parallel AI SDK - web search, content extraction, and async task runs
tags: [effect, sdk-wrapper, parallel-ai, http-client]
---

# Parallel SDK Effect Wrapper

Effect-native wrapper for the Parallel AI SDK. Injects Effect's HttpClient as the
fetch implementation, providing typed errors, deferred computation patterns, and
composable layer construction.

## Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         User Code                                │
│                    (Effect programs)                             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      ParallelClient                              │
│    ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│    │   search()   │  │  extract()   │  │   createRun()    │    │
│    └──────────────┘  └──────────────┘  └──────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Effect HttpClient                             │
│              (injected via Layer.provide)                        │
└─────────────────────────────────────────────────────────────────┘

## Core Modules

| Module | Purpose |
|--------|---------|
| `ParallelClient.ts` | Service interface with Effect operations |
| `ParallelClientLive.ts` | Live implementation using HttpClient |
| `ParallelRun.ts` | Async run execution with polling |
| `Errors.ts` | Tagged error types for failure handling |

## Usage Patterns

### Basic Search

```typescript
import * as Parallel from "@/packages/parallel"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const client = yield* Parallel.ParallelClient
  const results = yield* client.search({ query: "Effect TypeScript" })
  return results
})

const runnable = program.pipe(
  Effect.provide(Parallel.Live)
)

Error Handling

import * as Parallel from "@/packages/parallel"
import { Effect } from "effect"

const safe = program.pipe(
  Effect.catchTag("ParallelApiError", (e) =>
    Effect.succeed({ error: e.message })
  ),
  Effect.catchTag("ParallelNetworkError", () =>
    Effect.succeed({ error: "Network unavailable" })
  )
)

Design Decisions

AD-1: Inject HttpClient via Layer Enables testing with mock HTTP responses. Production uses FetchHttpClient, tests use a custom client that returns canned responses.

AD-2: Tagged errors for all failure modes ParallelApiError, ParallelNetworkError, ParallelTimeoutError. Enables precise error handling with catchTag.

Dependencies

• effect - Core runtime
• @effect/platform - HttpClient abstraction
• parallel-sdk - Underlying SDK (via .context/parallel-sdk-typescript)

Spec Reference

• specs/parallel/DESIGN.md

## When to Use This Skill

- Adding a new package or app that should be discoverable
- Documenting an existing module for AI assistants
- Creating context for external libraries added as submodules
- Updating documentation after significant refactoring
- Ensuring modules appear in `/modules` listings

## Key Principles

1. **Frontmatter is required** - path and summary enable indexing
2. **Summary is critical** - appears in all module listings
3. **Architecture diagrams** - visual overview aids understanding
4. **Usage patterns with imports** - show how to actually use the module
5. **Design decisions** - explain why, not just what
6. **Code examples compile** - include all necessary imports
7. **Namespace imports** - always `import * as X from`