Project Structure

What ck install writes: one canonical context file (AGENTS.md), a short always-loaded index, topic standards that load only where they apply, and five small skills.

Directory Overview

A typical project after ck install with Claude Code selected:

Directory structure created:

your-project/
├── AGENTS.md                     ← Canonical context file (every tool)
├── CLAUDE.md                     ← @AGENTS.md + @.contextkit/standards/index.md
├── .contextkit/
│   ├── standards/
│   │   ├── index.md              ← Always loaded, ≤50 lines (written by /ck setup)
│   │   ├── code-style.md         ← Coding conventions
│   │   ├── code-style/           ← Granular style guides
│   │   │   ├── css-style.md
│   │   │   └── typescript-style.md
│   │   ├── testing.md            ← Test patterns
│   │   ├── architecture.md       ← Architecture decisions
│   │   ├── ai-guidelines.md      ← AI behavior rules
│   │   ├── workflows.md          ← Team process
│   │   ├── glossary.md           ← Project terminology
│   │   └── README.md
│   ├── product/                  ← Product context
│   │   ├── mission.md
│   │   ├── mission-lite.md
│   │   ├── roadmap.md
│   │   ├── decisions.md
│   │   └── context.md
│   ├── goals/                    ← /goal files (created on first use)
│   ├── commands/                 ← Workflow files the skills point at
│   ├── templates/                ← goal.md, component.md, test.md, …
│   ├── hooks/                    ← pre-push, commit-msg
│   ├── quality-gates.yml         ← Pre-push gate config
│   ├── corrections.md            ← Corrections log (ck note, /learn)
│   └── config.yml                ← headline, context_rules, budget, …
│
├── .claude/
│   ├── rules/
│   │   ├── contextkit-testing.md     ← paths: test files
│   │   └── contextkit-code-style.md  ← paths: src/**, lib/**, …
│   └── skills/                   ← ck, doc, learn, goal, headline
└── .agents/skills/               ← Portable copy (Codex, Cursor)

ℹ️ Skeleton Files

Standards files start as blank templates. Run /ck setup in your AI tool to analyze the codebase and write the standards, index.md, and context_rules.

Context Files

ContextKit keeps one source of truth. Every integration writes the same AGENTS.md block; other tools either import it or get a copy of the same body.

AGENTS.md

The canonical context file, written inside ContextKit markers (your own text outside them is kept)

Always- Read .contextkit/standards/index.md first, read the active goal if there is one, check corrections.md
Read When Relevant- A table mapping tasks to files: code-style, testing, architecture, ai-guidelines, workflows, glossary, product decisions/roadmap
Skills- ck, doc, learn, goal, headline, plus a version stamp

CLAUDE.md

Imports the canonical file. Claude Code only reads AGENTS.md on its own when there is no CLAUDE.md, so the import keeps the two in step.

@AGENTS.md
@.contextkit/standards/index.md

Claude Code: skills run as /ck, /doc, /learn, /goal, /headline. Topic standards
load from .claude/rules/ when you touch matching files. When you need a decision,
ask with AskUserQuestion — concrete options, recommended first.

.contextkit/standards/index.md

New in 2.0. Always loaded and kept to 50 lines or fewer: what the project is, must / must-not rules, exact commands, and a "When you touch X → read Y" table. /ck setup writes it; /ck tidy keeps it short.

The .contextkit Directory

This is where your project standards and context files live:

standards/

Topic standards — loaded when relevant, not every session

index.md- Short always-loaded summary and pointers
code-style.md- YOUR coding conventions
code-style/- Granular style guides (CSS, TypeScript)
testing.md- YOUR test patterns
architecture.md- YOUR architecture decisions
ai-guidelines.md- AI behavior rules (commits, when to ask)
workflows.md- Team process (branches, releases)
glossary.md- YOUR project terminology
frontend/ backend/- Scope-specific standards (monorepos)

product/

Product context for AI understanding

mission.md- Product vision and purpose
mission-lite.md- Condensed mission for AI context
roadmap.md- Development phases and features
decisions.md- Architecture Decision Records (ADRs)
context.md- Domain-specific context

goals/

One-page goal files for long-running tasks (.contextkit/goals/<slug>.md). AGENTS.md tells the agent to read the active one before starting work. See /goal.

corrections.md

Corrections log

Tracks AI behavior issues and preferences. Add entries with ck note, or use /learn to turn a correction into a rule in the right standards file.

config.yml

Project configuration (format_version: 2)

headline- true|false — the always-on headline reply style
diagrams_in_docs- Allow Mermaid diagrams in generated docs (default false)
context_rules- Which topic standards load for which paths (see below)
context_budget_lines- Warn when always-loaded context passes this many lines (default 400)

instructions/ and policies/

Pre-/post-flight workflow instructions and policy.yml enforcement levels (off, warn, block).

Path-Scoped Rules

context_rules in .contextkit/config.yml maps each topic standards file to the paths it applies to. These are the defaults:

context_rules:
  - file: standards/testing.md
    paths: ["**/*.test.*", "**/*.spec.*", "**/__tests__/**"]
  - file: standards/code-style.md
    paths: ["src/**", "lib/**", "app/**", "packages/**"]

/ck setup and /ck tidy maintain the list; ck install renders it in each tool's format. After editing it by hand, re-render with ck update --force or ck <platform> (e.g. ck claude):

Tool	File	Frontmatter
Claude Code	`.claude/rules/contextkit-<name>.md`	`paths:`
Cursor	`.cursor/rules/contextkit-<name>.mdc`	`globs:`
GitHub Copilot	`.github/instructions/contextkit-<name>.instructions.md`	`applyTo:`

Stale contextkit-* rule files are removed when they drop out of the list. Your own rule files are never touched.

ℹ️ Fixed in 2.0

Before 2.0, the Claude rule files used globs:, which Claude Code ignores — so they loaded in every session. They now use paths: and only load when you touch matching files.

Platform-Specific Integrations

Every integration writes AGENTS.md, then adds what its tool needs:

Claude Code - CLAUDE.md + .claude/rules/ + .claude/skills/

CLAUDE.md imports AGENTS.md and index.md. Topic standards load from path-scoped .claude/rules/. Run /context in Claude Code to see what is loaded.

Codex / OpenCode - AGENTS.md + .codex/skills/ + .agents/skills/

Read AGENTS.md directly. In Codex, skills run as $ck, $doc, and so on.

Cursor - .cursor/rules/ + .cursor/prompts/

Reads AGENTS.md, plus path-scoped contextkit-<name>.mdc rules. Skills are in .cursor/prompts/ and .agents/skills/.

Gemini CLI - GEMINI.md

A short pointer plus @AGENTS.md.

Copilot, Windsurf, Aider - mirror files

.github/copilot-instructions.md, .windsurfrules, and CONVENTIONS.md get the same body as AGENTS.md, since these tools may not read it. Copilot also gets path-scoped .github/instructions/ files.

Continue.dev - .continue/rules/

A ContextKit rule file pointing at the standards, for Continue in any editor.

Customization

Everything in .contextkit/ is yours to edit. After running /ck setup in your AI tool, tune it to your team:

Keep the must-know rules and commands in index.md — short
Put topic detail in code-style.md, testing.md, architecture.md and friends
Point topic files at the paths they apply to with context_rules
Add project terminology to glossary.md
Capture decisions in product/decisions.md
Use /learn when you correct the AI, so the rule sticks
Run /ck tidy when always-loaded context grows (ck check --context warns past the budget)

Pro Tip

Write rules the AI can't infer from your code or config — specific, project-only conventions. Generic advice and anything your linter already enforces just adds noise.

Quick Start

Upgrading to 2.0

Was this helpful?

Help us improve the documentation by sharing your feedback.