Core Concepts

Blocks

Blocks are reusable context snippets stored as Markdown files with YAML frontmatter. Each block focuses on a specific topic or technology.

---
name: Laravel Base
description: Laravel framework conventions
version: 1.0.0
tags: [laravel, php]
---

## Laravel Conventions

- Use Form Requests for validation
- Keep controllers thin
- Prefer Eloquent over raw queries
- Use Jobs for background processing

Blocks are stored in ~/.contextmark/blocks/ and can be organized in folders like laravel/base.md.

Profiles

Profiles are YAML files that combine multiple blocks into a coherent context set for specific project types.

name: Laravel Package
description: For developing Laravel packages
blocks:
  - laravel/base
  - laravel/testing
  - style/code
  - style/git
agents:
  - reviewer
  - tester
commands:
  - deploy

When you initialize a project with a profile, all the specified blocks are combined into a single CLAUDE.md.

Agents

Agents are reusable AI assistant configurations stored as Markdown files with specific instructions.

---
name: Code Reviewer
description: Review code for quality and best practices
---

When reviewing code, focus on:
- Code readability and maintainability
- Performance considerations
- Security vulnerabilities
- Test coverage

Agents are copied to your project's .claude/skills/ directory when you initialize with a profile or use contextmark add-agent.

Commands

Commands are reusable slash command definitions for Claude Code.

---
name: Deploy
description: Deploy the application to production
---

Before deploying:
1. Run all tests
2. Check for uncommitted changes
3. Verify environment variables
4. Build production assets

Commands are copied to your project's .claude/commands/ directory.

Library Structure

~/.contextmark/

├── config.yml # Global configuration

├── blocks/ # Reusable context blocks

│ ├── laravel/

│ │ ├── base.md

│ │ └── testing.md

│ └── style/

│ ├── code.md

│ └── git.md

├── profiles/ # Block combinations

│ ├── laravel-package.yml

│ └── default.yml

├── agents/ # Reusable agents

│ └── reviewer.md

├── commands/ # Custom commands

│ └── deploy.md

└── global/ # Global context

└── CLAUDE.md

Project Files

When you initialize a project, ContextMark creates:

CLAUDE.md

The generated context file that Claude Code reads. Composed from your profile's blocks.

.contextmark.yml

Tracks which profile and block versions are used, enabling update detection.