Context Creator

This is the most important skill in the system. Every other skill depends on the context files this one creates.

AI agents are smart. They can infer a lot. But they cannot infer what was never captured. The difference between an agent that builds the right thing and an agent that builds something close is context. Not more context — the right context, organized so the agent loads what it needs when it needs it.

This skill extracts that context from the developer through a structured interview — section by section, confirmed as you go — and produces the complete set of project context files. Every future session, every other skill, reads these files before doing anything.

How to Invoke

For a new project (starting from an idea, problem statement, or SRS):

/context-creator new

For an existing codebase (project already has code, needs context files):

/context-creator scan

What Gets Generated

All files are created in the project root, flat alongside AGENTS.md:

Not every project needs every file. The interview determines which are relevant. But the interview always asks — the developer decides what to skip.

Mode 1 — New Project (/context-creator new)

Step 0 — Absorb What the Developer Gives

The developer might give you:

• An SRS document
• A problem statement
• A verbal idea
• A feature list
• A design mockup description
• Nothing — just a conversation

Whatever they give, read it completely before starting the interview. Extract every fact, requirement, and decision from it. Do not ask about anything the input already answers clearly.

Then say:

I've read through everything you shared. Here's what I understand so far:

[2-3 sentence summary of what the project is and what it does]

I'm going to walk through [X] sections to fill in the full context.
Each section, I'll ask questions, we'll confirm, and move on.

Let's start.

Step 1 — Project Overview

Interview for project-overview.md.

Ask (skip anything already answered by the input):

Section 1: Project Overview

1. What is this project in one sentence?
2. Who is it for? (target users / audience)
3. What problem does it solve?
4. What are the core features? (list the main things it does)
5. What type of application is this? (web app, mobile, API, CLI, monorepo, etc.)
6. Is there a business model? (SaaS, marketplace, internal tool, etc.)

After the developer answers, summarize what you captured for this section:

Here's what I captured for Project Overview:

[Summary]

Correct? Say yes to lock this in, or correct anything.

Only after confirmation, move to the next section.

Step 2 — Tech Stack and Libraries

Interview for library-docs.md and stack section of AGENTS.md.

Section 2: Tech Stack & Libraries

1. What language(s) and framework(s)?
2. What database(s)?
3. What package manager and build tool?
4. What testing framework?
5. Any key libraries already decided on? For each one:
   - What is it for?
   - Why this library over alternatives?
6. Any libraries or tools that should NOT be used?
7. Runtime and deployment target? (Node version, Docker, cloud provider, etc.)

Summarize → confirm → move on.

Step 3 — Architecture

Interview for architecture.md.

Section 3: Architecture

1. What is the high-level architecture?
   (monolith, monorepo, microservices, serverless, etc.)
2. What are the main modules/apps/services?
   For each one:
   - What is it responsible for?
   - What does it depend on?
   - What does it expose to other modules?
3. Where does shared code live? (shared types, utilities, constants)
4. What are the hard boundaries?
   (e.g., "UI never calls database directly",
    "services communicate only through APIs/queues")
5. How does data flow through the system?
   (request → where → what processing → response)

Summarize → confirm → move on.

Step 4 — Communication Flow

Interview for communication-flow.md.

Section 4: Communication Flow

1. Do services/modules communicate asynchronously?
   (message queues, event bus, webhooks, pub/sub)
2. If yes — what technology? (RabbitMQ, Kafka, Redis pub/sub, SQS, etc.)
3. What are the main flows?
   (e.g., order → queue → payment → queue → notification → email)
4. What happens when a message fails? (retry, dead letter queue, manual?)
5. Are there any synchronous service-to-service calls? (REST, gRPC, etc.)
6. Any real-time communication? (WebSockets, SSE, polling)

If this project has no async communication, we'll skip this file.

If not applicable, confirm skip and move on.

Summarize → confirm → move on.

Step 5 — API Contracts

Interview for api-contracts.md.

Section 5: API Contracts

1. What API style? (REST, GraphQL, gRPC, tRPC, etc.)
2. What is the base URL structure? (e.g., /api/v1/[resource])
3. What are the main resource groups / endpoints?
   For each group:
   - What endpoints exist? (GET, POST, PUT, DELETE)
   - What are the key request/response shapes?
4. What is the standard error response format?
5. What HTTP status codes are used and what do they mean in this project?
6. Is there API versioning? How?
7. Any rate limiting or pagination patterns?

If the project has no API, we'll skip this file.

If not applicable, confirm skip and move on.

Summarize → confirm → move on.

Step 6 — Security

Interview for security.md.

Section 6: Security

1. How is authentication handled?
   (JWT, session, OAuth, magic links, etc.)
2. Is there role-based access control (RBAC)?
   If yes — what are the roles and what can each access?
3. What data is considered sensitive?
   (personal info, financial data, documents, location, etc.)
4. How are API endpoints protected?
   (auth middleware, API keys, rate limiting, etc.)
5. Are there any compliance requirements?
   (GDPR, HIPAA, SOC2, etc.)
6. How are secrets managed?
   (env vars, vault, cloud secrets manager, etc.)
7. Any file upload security considerations?
   (type validation, size limits, storage location)

If the project has no security concerns, we'll note that and move on.

Summarize → confirm → move on.

Step 7 — Code Standards

Interview for code-standards.md.

Section 7: Code Standards

1. File naming convention?
   (PascalCase, kebab-case, camelCase — for components, utils, tests)
2. Folder structure — what does a feature/module look like?
3. Function/variable naming convention?
4. How are types/interfaces defined?
   (co-located, centralized, per-module)
5. Error handling pattern?
   (try-catch, Result types, error boundaries, global handler)
6. Import ordering preference?
7. Any linting or formatting rules beyond defaults?
   (ESLint config, Prettier, Biome, etc.)
8. How are tests organized?
   (co-located, separate folder, naming convention)
9. Any patterns that are enforced or banned?

Summarize → confirm → move on.

Step 8 — UI Rules

Interview for ui-rules.md.

Section 8: UI Rules

1. Does this project have a frontend/UI?
   [If no — skip this section and ui-tokens.md]

2. What UI framework/library? (React, Vue, Svelte, vanilla, etc.)
3. What styling approach?
   (Tailwind, vanilla CSS, CSS modules, styled-components, SCSS, etc.)
4. Is there a component library? (shadcn, MUI, Ant Design, custom, etc.)
5. What is the layout system? (grid, flexbox, responsive breakpoints)
6. What are the component design principles?
   (e.g., "every card has header + body + optional footer")
7. How is responsive design handled?
   (mobile-first, desktop-first, breakpoint strategy)
8. Are there animation/transition standards?
9. Dark mode / theming support?
10. Any accessibility requirements or standards?

Summarize → confirm → move on.

Step 9 — UI Tokens

Interview for ui-tokens.md. Only if the project has a UI.

Section 9: UI Tokens (Design Tokens)

1. Color palette — what are the primary, secondary, accent,
   background, surface, text, and error colors?
2. How are colors defined?
   (CSS variables, Tailwind config, SCSS variables, theme object)
3. Typography scale — what fonts, sizes, and weights?
4. Spacing scale — what spacing values are used?
   (4px, 8px, 16px system? Tailwind scale? Custom?)
5. Border radius values?
6. Shadow values?
7. Any brand-specific design tokens?

If the developer doesn't have these decided yet, note that
ui-tokens.md will be populated later (possibly via /imprint audit).

Summarize → confirm → move on.

Step 10 — Build Plan

Interview for build-plan.md.

Section 10: Build Plan

1. What is the MVP? (minimum set of features to launch)
2. What comes in V1 after MVP?
3. What is planned for V2 / future?
4. Are there any hard deadlines or milestones?
5. What is the deployment strategy?
   (CI/CD, manual, staging → production, etc.)
6. Any dependencies between features?
   (e.g., "auth must be built before user profiles")

Summarize → confirm → move on.

Step 11 — Final Review

After all sections are confirmed, present the complete plan of what will be generated:

All sections captured. Here's what I'll generate:

1. AGENTS.md — index referencing all context files
2. project-overview.md — [one-line summary]
3. architecture.md — [one-line summary]
4. communication-flow.md — [one-line summary] [or SKIPPED]
5. code-standards.md — [one-line summary]
6. ui-rules.md — [one-line summary] [or SKIPPED]
7. ui-tokens.md — [one-line summary] [or SKIPPED]
8. library-docs.md — [one-line summary]
9. security.md — [one-line summary]
10. api-contracts.md — [one-line summary] [or SKIPPED]
11. build-plan.md — [one-line summary]
12. progress-tracker.md — initialized empty

Ready to generate all files? Say yes to proceed,
or tell me what to change.

Only after approval, generate all files.

Step 12 — Generate All Files

Write all files. Each file should be concise, scannable, and useful — not walls of text.

After writing, create progress-tracker.md initialized with the build plan phases:

# Progress Tracker

Last updated: [date]

## MVP
- [ ] [Feature 1]
- [ ] [Feature 2]
- [ ] [Feature 3]

## V1
- [ ] [Feature 4]
- [ ] [Feature 5]

## V2 / Future
- [ ] [Feature 6]
- [ ] [Feature 7]

Step 13 — Generate AGENTS.md (The Index)

AGENTS.md is the master file that every agent session reads. It contains:

1. A brief project summary (2-3 lines max)
2. The tech stack (brief)
3. Critical rules that apply to EVERY session (keep this short)
4. References to all context files with one-line descriptions

# [Project Name]

[One paragraph: what this project is and what it does]

## Stack
[Language, framework, database, key tools — one line each]

## Critical Rules
[5-10 rules that apply to EVERY session — the non-negotiable ones]
- [Rule 1]
- [Rule 2]
- ...

## Context Files
Read these files when working on related areas:

- [project-overview.md](./project-overview.md) — what the project is, who it's for, core features
- [architecture.md](./architecture.md) — system design, module boundaries, data flow
- [communication-flow.md](./communication-flow.md) — async messaging, event flows, service-to-service
- [code-standards.md](./code-standards.md) — naming, file structure, error handling, patterns
- [ui-rules.md](./ui-rules.md) — design system rules, component patterns, layout
- [ui-tokens.md](./ui-tokens.md) — colors, spacing, typography, design tokens
- [library-docs.md](./library-docs.md) — key libraries and why they were chosen
- [security.md](./security.md) — auth model, RBAC, sensitive data, API security
- [api-contracts.md](./api-contracts.md) — API endpoints, request/response, status codes
- [build-plan.md](./build-plan.md) — phased implementation plan
- [progress-tracker.md](./progress-tracker.md) — current progress and what's next

## Auto-Generated (by skills)
- [memory.md](./memory.md) — session continuity (by /remember)
- [ui-registry.md](./ui-registry.md) — UI component patterns (by /imprint)

Step 14 — Confirm Completion

Context created. [X] files generated.

Your project now has full context for any AI agent session.

How to use:
- Every session reads AGENTS.md automatically
- Agents load specific context files when working on related areas
- Run /remember save at end of sessions to maintain memory
- Run /imprint after building UI components to track patterns
- Update progress-tracker.md as features are completed

To update any context file later, just edit it directly
or re-run /context-creator scan to regenerate from the current codebase.

Mode 2 — Existing Project (/context-creator scan)

Step 0 — Deep Scan the Codebase

Before asking the developer anything, read the codebase thoroughly:

1. Project structure — read the full directory tree. Understand what exists.
2. Package files — package.json, requirements.txt, Cargo.toml, go.mod, etc. Identify all dependencies.
3. Configuration files — tsconfig.json, .eslintrc, nx.json, docker-compose.yml, vite.config.ts, etc.
4. Entry points — main app files, route definitions, API handlers.
5. Existing context files — any AGENTS.md, CLAUDE.md, README.md, .cursorrules, etc.
6. Database schema — Prisma schema, migrations, SQL files, models.
7. Key components — read a representative sample of components, services, utilities to understand patterns.
8. Test files — read a sample of tests to understand testing patterns.
9. Environment files — .env.example, .env.development, etc.
10. CI/CD and deployment — GitHub Actions, Docker files, deploy scripts.

Build a complete mental model of:

• What this project is and does
• What technology it uses and why
• How it's structured (modules, boundaries, data flow)
• What patterns it follows (naming, error handling, file structure)
• What its UI looks like (if applicable)
• What its security model is
• What APIs it exposes
• How services communicate

Step 1 — Present Your Understanding

Present what you found to the developer before starting the interview:

I've scanned the codebase. Here's what I found:

**Project:** [what it is]
**Stack:** [languages, frameworks, database, tools]
**Structure:** [monolith/monorepo/microservices, key modules]
**Patterns:** [key patterns observed]
**Size:** [rough scale — number of modules, routes, components]

I'll now walk through each section to confirm my understanding
and fill in anything the codebase doesn't tell me
(like "why" decisions were made, business context, future plans).

Let's start.

Step 2-11 — Same Interview, But Pre-Filled

Walk through the same sections as Mode 1, but pre-fill answers from the scan. For each section:

1. Present what you found in the codebase
2. Ask the developer to confirm or correct
3. Ask only the questions the codebase cannot answer (business context, reasoning, future plans)

Section [X]: [Section Name]

Here's what I found in the codebase:
[Pre-filled answers from the scan]

Questions the codebase doesn't answer:
1. [Question that requires human context]
2. [Question about reasoning or intent]

This makes the interview much faster for existing projects — the developer only fills gaps, not everything from scratch.

Step 12-14 — Same as Mode 1

Generate all files, present for review, write after approval.

Updating Context Files

Context files are living documents. They should be updated when:

• A new module or service is added → update architecture.md
• A new library is added → update library-docs.md
• API endpoints change → update api-contracts.md
• A build phase is completed → update progress-tracker.md and build-plan.md
• Security model changes → update security.md
• UI design system changes → update ui-rules.md and ui-tokens.md

The developer can update these manually, or re-run /context-creator scan to regenerate from the current codebase state.

Principles

Extract, don't invent. Capture what the developer knows. Do not make up requirements, architecture, or decisions they haven't confirmed.

Confirm before writing. Every section is confirmed before moving on. Every file set is approved before writing. Nothing gets generated that the developer hasn't agreed to.

Concise over comprehensive. Each file should be scannable — not a wall of text. If a section takes more than a page to read, it's too long. Agents are smart — give them the right signals, not a textbook.

The developer's time is the bottleneck. Ask smart questions. Pre-fill what you can. Don't ask what the code already tells you. Every question should earn its place in the interview.