Related Pages

Related topics: Architecture: Layered Config, Agents, Commands, Skills, and Hooks, Template Variants and Per-Stack Customization, Setup, Deployment, Verification, and Workflow Operations

Introduction to the Claude Code Toolkit

The Claude Code Toolkit is a community-oriented repository that gathers reusable resources, conventions, and operational guidance for working with Anthropic's Claude Code CLI and its agent-based workflows. Rather than acting as a single binary or runtime library, the toolkit functions as a curated knowledge base: it documents how contributors and users should structure their work, how agent configurations should be authored, and how the project itself evolves over time Source: README.md:1-20. The repository's primary audience is developers, prompt engineers, and automation authors who build, share, or extend Claude Code agents and tooling.

The toolkit's purpose is twofold. First, it standardizes the conventions that govern Claude Code agent definitions so that artifacts authored by different contributors remain interoperable. Second, it provides a transparent record of changes, contribution expectations, and community norms so that the project can scale without sacrificing clarity or trust Source: CONTRIBUTING.md:1-15.

Repository Layout and Documentation Roles

The repository is organized as a documentation- and configuration-first project. Each top-level Markdown file plays a distinct role in defining how the project is understood, maintained, and extended.

This separation of concerns allows each policy area to evolve independently. For example, agent conventions can be amended in AGENTS.md without requiring a re-read of contribution policy text, and security disclosures follow the dedicated channel described in SECURITY.md Source: SECURITY.md:1-10.

Agent Authoring Conventions

A central concern of the toolkit is the consistent authoring of agents. AGENTS.md acts as the canonical reference for naming patterns, required frontmatter, capability declarations, and the relationship between an agent's declared tools and its intended behavior. New agents added to the repository are expected to comply with these conventions so that downstream automation can discover, validate, and load them predictably Source: AGENTS.md:1-25.

While the toolkit does not prescribe a specific runtime, it is designed to align with Claude Code's notion of an agent as a configured entity with explicit tools, prompts, and execution boundaries. The conventions documented in AGENTS.md therefore emphasize clarity over brevity: contributors are encouraged to document the intent, inputs, and limitations of every agent they submit Source: AGENTS.md:25-50.

Change Management and Versioning

CHANGELOG.md provides the audit trail for the toolkit's evolution. Entries typically reference the affected agent(s) or convention section, the nature of the change (addition, deprecation, breaking change), and any migration steps required by downstream users. The presence of a structured changelog signals that the project treats backward compatibility — at least at the documentation and convention layer — as a first-class concern Source: CHANGELOG.md:1-15.

For contributors, the changelog functions as both a release note and a checklist: pull requests that introduce observable changes are expected to be paired with a corresponding entry. This keeps the history scannable and reduces the risk of undocumented behavioral drift between revisions Source: CONTRIBUTING.md:15-35.

Community and Contribution Workflow

The contribution workflow is intentionally lightweight but explicit. Prospective contributors are expected to read CONTRIBUTING.md first, which describes how to open issues, structure pull requests, and engage with reviewers. Submissions that add new agents must also conform to AGENTS.md, while submissions that change conventions or defaults must update the relevant documentation in the same change Source: CONTRIBUTING.md:1-50.

Community behavior is governed by CODE_OF_CONDUCT.md, which sets expectations for respectful collaboration and outlines the reporting path for violations. Security-sensitive disclosures are intentionally routed through a separate process documented in SECURITY.md, so that vulnerability reports are not conflated with general issue traffic Source: CODE_OF_CONDUCT.md:1-20.

Working with the Toolkit

For a new user, the recommended path through the repository is:

1. Read README.md to understand scope and intended use.
2. Consult AGENTS.md before authoring or modifying any agent definition.
3. Review CHANGELOG.md to confirm the conventions in effect for the current revision.
4. Follow CONTRIBUTING.md when preparing a change for submission.
5. Use SECURITY.md and CODE_OF_CONDUCT.md as references for responsible disclosure and community interaction.

Because the toolkit is documentation-driven, the fastest way to become effective with it is to internalize the conventions it encodes rather than to look for a single executable entry point. The repository's value scales with the consistency of the contributions it accepts, which is precisely why each policy file is treated as a load-bearing component of the project Source: README.md:20-40.

Related Pages

Related topics: Introduction to the Claude Code Toolkit, Template Variants and Per-Stack Customization, Setup, Deployment, Verification, and Workflow Operations

Architecture: Layered Config, Agents, Commands, Skills, and Hooks

Purpose and Scope

The claude-code-toolkit is organized around five composable layers: configuration, agents, commands, skills, and hooks. Each layer has a single, well-defined responsibility, which keeps the system predictable and makes policy enforcement explicit. By separating *what the model decides* (agents, commands, skills) from *what the environment guarantees* (config, hooks), the toolkit reduces ambiguity and improves auditability.

The architecture is described at a high level in docs/architecture.md, while the philosophy and enforcement strategy for hooks is elaborated in docs/hook-enforcement-ideas.md. Concrete enforcement is implemented by four shell scripts in hooks/ that gate version-control operations and protected branches.

Source: docs/architecture.md, docs/hook-enforcement-ideas.md.

Layered Configuration

Configuration in the toolkit is layered so that defaults, repository-level settings, and per-user overrides compose in a documented order. The docs/architecture.md file specifies the precedence model and identifies which files contribute to each layer.

The conceptual reading order is:

1. Built-in defaults shipped with the toolkit
2. Repository configuration committed alongside the project (e.g. .claude/)
3. User overrides applied in the developer's local environment

Later layers override earlier ones, but only for keys they explicitly declare. This means that policy tightening happens locally without forking the toolkit, while shared defaults remain consistent across teams. The layering also makes it possible to trace *why* a given setting is in effect by checking each layer in order.

Source: docs/architecture.md.

Agents, Commands, and Skills

Agents, commands, and skills are the three extension surfaces that determine what the model and the user can do. They are intentionally kept separate so each has a clear trigger model and audit story.

Agents model long-lived roles. An agent loads its system prompt, selects which tools it may call, and delegates cross-cutting work to skills. Commands are short, deterministic entry points that the user types directly. They are ideal for repeatable workflows such as generating a changelog or opening a pull request. Skills are pure capabilities that do not decide *when* to run; they only describe *how* a task is accomplished once invoked.

Keeping these three surfaces distinct avoids hidden side effects. A skill, for example, can be safely composed from any agent or command without owning the decision to trigger itself. Source: docs/architecture.md.

Hooks as the Policy Layer

Hooks are the enforcement boundary of the toolkit. They run at lifecycle events and make deterministic, fail-closed decisions that must not depend on the model's reasoning. The docs/hook-enforcement-ideas.md file codifies the principles: hooks should be fast, locally executable, exit non-zero on violation, and never silently rewrite user intent.

Four hooks ship with the toolkit, each covering a specific policy concern:

• hooks/block-bash-vcs.sh — blocks unsupported or dangerous version-control shell actions invoked through the agent.
• hooks/no-push-main.sh — rejects direct pushes to the protected main branch.
• hooks/gate-before-merge.sh — runs required checks before a merge is allowed to proceed.
• hooks/pre-commit-test.sh — executes the project's test suite before a commit is accepted.

Each script is small enough to be reviewed as a unit of policy. Hooks do not attempt to repair violations; they report and exit non-zero so that the surrounding tool, git, or agent runtime treats the action as a hard stop. Source: docs/hook-enforcement-ideas.md.

Source: hooks/block-bash-vcs.sh, hooks/no-push-main.sh, hooks/gate-before-merge.sh, hooks/pre-commit-test.sh.

Workflow Integration

The layers compose into a single request flow. When a user triggers a command or the model invokes a skill, the action ultimately reaches a host event (git commit, git push, merge request, shell call). At that point the relevant hook runs and decides pass or fail. Failures short-circuit the operation; successes let it continue normally.

flowchart TD
  A[User / Agent action] --> B[Command or Skill invoked]
  B --> C{Hook gate}
  C -- pass --> D[Operation continues]
  C -- fail --> E[Hard stop, exit non-zero]

This gate pattern is shared by every hook in hooks/. By placing the gate at the boundary between the agent and the host system, the toolkit ensures that no policy decision depends on the model's compliance — the host sees only the script's exit code.

Source: docs/architecture.md, docs/hook-enforcement-ideas.md.

Summary

• The toolkit separates concerns across config, agents, commands, skills, and hooks
• Configuration is layered with explicit precedence: defaults → repo → user
• Agents model roles, commands model user actions, and skills model reusable behaviors
• Hooks provide deterministic, fail-closed policy enforcement at lifecycle events
• Shipped hooks cover VCS command blocking (block-bash-vcs.sh), protected-branch protection (no-push-main.sh), merge gating (gate-before-merge.sh), and pre-commit testing (pre-commit-test.sh)
• All policy decisions funnel through a uniform gate pattern so that the host runtime enforces rules independently of the model

Source: docs/architecture.md, docs/hook-enforcement-ideas.md, hooks/block-bash-vcs.sh, hooks/no-push-main.sh, hooks/gate-before-merge.sh, hooks/pre-commit-test.sh.

Related Pages

Related topics: Architecture: Layered Config, Agents, Commands, Skills, and Hooks, Setup, Deployment, Verification, and Workflow Operations

Template Variants and Per-Stack Customization

Purpose and Scope

The claude-code-toolkit ships a curated set of project bootstrap templates that Claude Code can consume when initializing a new repository or refreshing an existing one. Templates are organized by technology stack, allowing each variant to encode stack-specific conventions, build commands, agent roles, and project conventions while sharing a common document layout Source: docs/templates.md. The general-purpose variant under templates/general/ defines the canonical four-file layout that other stack variants extend or override.

The role of per-stack customization is to ensure that when a user picks a stack (e.g., general), the resulting workspace contains prompts and context files that already encode relevant tooling, test runners, and architectural defaults — rather than requiring the user to author them from scratch Source: docs/templates.md.

Template File Layout

Every stack variant follows the same four-file contract, illustrated below by the general stack Source: templates/general/CLAUDE.md Source: templates/general/AGENT_TEAM.md Source: templates/general/PROJECT_CONTEXT.md Source: templates/general/PROJECT_STATE.md:

This contract means a downstream tool (or the template-sync workflow) can rely on a predictable file shape regardless of the chosen stack Source: docs/templates.md. Stack-specific variants follow the same four-file shape but tailor the contents — for example, a Python stack might override test commands in CLAUDE.md while keeping the AGENT_TEAM.md structure identical to the general variant.

Per-Stack Customization Mechanism

Per-stack customization is achieved through directory-scoped overrides under templates/<stack>/. The general directory functions as the baseline: its four files establish defaults that downstream variants can inherit conceptually while substituting stack-specific content Source: templates/general/CLAUDE.md.

The customization surface includes:

• Behavioral defaults (CLAUDE.md) — coding style, commit conventions, tool preferences, and verification commands tailored to the stack's ecosystem.
• Agent topology (AGENT_TEAM.md) — which specialist agents exist (e.g., reviewer, tester, migrator) and how they hand off work.
• Project framing (PROJECT_CONTEXT.md) — domain assumptions, build systems, and runtime environments characteristic of the stack.
• State scaffolding (PROJECT_STATE.md) — initial checkpoints and progress markers appropriate to typical projects in that stack.

Because every variant lives in its own folder and adheres to the same filenames, copy and merge operations remain mechanical and idempotent Source: docs/template-sync.md.

Template Synchronization

The docs/template-sync.md document describes how updates to upstream templates propagate into consumer projects. Synchronization preserves the per-stack structure while reconciling drift between the toolkit's source of truth and a user's local checkout Source: docs/template-sync.md.

flowchart LR
    A[Toolkit Repo<br/>templates/&lt;stack&gt;/] -->|sync| B[Consumer Project<br/>.claude/]
    B -->|diff report| C{Conflicts?}
    C -- no --> D[Apply update]
    C -- yes --> E[Prompt user<br/>resolution]
    D --> F[Updated workspace]
    E --> F

The sync workflow is stack-aware: it only considers files present in the chosen stack variant and leaves any local additions untouched Source: docs/template-sync.md. This makes upgrading safe even when a consumer has customized their PROJECT_CONTEXT.md or PROJECT_STATE.md heavily.

Practical Guidance

When adopting a stack variant:

1. Select the directory under templates/ that matches the project's primary stack; fall back to general if no specialized variant exists Source: docs/templates.md.
2. Copy the four canonical files into the target workspace, preserving names so tooling can locate them.
3. Customize PROJECT_STATE.md immediately — it is the most frequently mutated file and drives day-to-day continuity Source: templates/general/PROJECT_STATE.md.
4. Re-run the template sync workflow after toolkit upgrades; review diffs in CLAUDE.md and AGENT_TEAM.md first since behavioral changes appear there Source: docs/template-sync.md.

This combination of a fixed four-file contract, stack-scoped overrides, and a deterministic sync process is what allows the toolkit to deliver per-stack customization without sacrificing the consistency Claude Code needs to operate reliably across heterogeneous projects Source: docs/templates.md Source: docs/template-sync.md.

Related Pages

Related topics: Introduction to the Claude Code Toolkit, Architecture: Layered Config, Agents, Commands, Skills, and Hooks, Template Variants and Per-Stack Customization

Setup, Deployment, Verification, and Workflow Operations

Purpose and Scope

The Setup, Deployment, Verification, and Workflow Operations area of claude-code-toolkit is responsible for transforming a fresh checkout into a working development environment, validating that the installation is correct, and providing repeatable operational procedures (audits, recovery, and configuration hygiene) used throughout the lifecycle of the project.

The toolkit ships a cross-platform installer pair — setup-project.sh for POSIX systems and setup-project.ps1 for Windows — backed by documentation in docs/setup.md and docs/getting-started.md. After installation, docs/verification.md defines the contract for a healthy environment, and docs/workflow-audit.md documents the operational checks that keep the workflow sound over time. Source: docs/setup.md; docs/getting-started.md.

Setup and Installation

Cross-platform Installer Scripts

The repository provides two equivalent entry points:

Both scripts expose a common lifecycle: validate prerequisites, prepare the working directory, install dependencies, copy or render configuration templates, and emit a final status summary. Source: setup-project.sh; setup-project.ps1.

Typical invocation patterns documented in the project:

# POSIX
./setup-project.sh

# Windows PowerShell
./setup-project.ps1

docs/getting-started.md is the recommended first stop for new users because it links prerequisites, the installer choice, and the verification steps into a single ordered sequence. Source: docs/getting-started.md.

Prerequisites and Configuration

docs/setup.md is the authoritative reference for what must exist before running an installer: required runtimes, supported operating systems, required environment variables, and any network access needed to fetch dependencies. Configuration templates rendered by the installer are referenced from this document so that users can audit the resulting state immediately after installation. Source: docs/setup.md.

Deployment

Deployment in this toolkit is intentionally lightweight: the same scripts used for first-time setup are also the recommended way to bring an environment to a known configuration. Re-running the installer is treated as an idempotent operation rather than a separate "deploy" pipeline. Source: docs/setup.md; setup-project.sh.

This design choice means:

• No separate deployment artifact is produced — the working tree plus installed dependencies is the deployable unit.
• Configuration is template-driven: changes to configuration files are tracked in the repository and re-applied by the installer.
• Windows and POSIX parity is maintained by keeping setup-project.sh and setup-project.ps1 functionally aligned. Source: setup-project.ps1.

Verification

docs/verification.md defines what "correctly installed" means for claude-code-toolkit. The verification stage covers:

1. File presence checks — expected files and directories exist after the installer runs.
2. Executable permissions — scripts such as setup-project.sh remain executable.
3. Dependency resolution — required runtimes and packages respond to version probes.
4. Configuration rendering — generated config files contain expected keys and values.
5. Smoke test commands — the documented commands can be invoked without error.

Running verification after every setup or upgrade is the contract enforced by the project. Source: docs/verification.md.

Workflow Operations and Audit

Long-running projects accumulate drift: stale configs, leftover artifacts, undocumented shortcuts. docs/workflow-audit.md defines a recurring audit procedure to detect and remediate that drift. The audit is organized around the same phases as setup — files, permissions, dependencies, configuration — but checks them against the *expected* state rather than only their *presence*. Source: docs/workflow-audit.md.

flowchart LR
    A[Install / Re-run setup] --> B[Verification]
    B -- pass --> C[Daily Use]
    B -- fail --> D[Remediate]
    C --> E[Periodic Audit]
    E -- drift --> D
    E -- clean --> C
    D --> A

The loop above is the operational heart of the toolkit: setup produces a known state, verification proves it, daily use proceeds, and the audit catches slow divergence before it becomes an incident. Source: docs/workflow-audit.md; docs/verification.md.

Operational Best Practices

• Always run verification immediately after setup-project.sh / setup-project.ps1. Source: docs/verification.md.
• Treat the audit as a scheduled task, not an ad-hoc step. Source: docs/workflow-audit.md.
• Keep docs/getting-started.md as the onboarding entry point; deeper detail lives in docs/setup.md. Source: docs/getting-started.md; docs/setup.md.

Summary

Setup, Deployment, Verification, and Workflow Operations form a single closed loop in claude-code-toolkit. The setup-project.sh and setup-project.ps1 installers establish the environment; docs/setup.md and docs/getting-started.md document the how and why; docs/verification.md proves correctness; and docs/workflow-audit.md guards against drift. Used together, they give every contributor — regardless of operating system — the same deterministic path from a clean checkout to a healthy, auditable working environment. Source: setup-project.sh; setup-project.ps1; docs/setup.md; docs/getting-started.md; docs/verification.md; docs/workflow-audit.md.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/dagonet/claude-code-toolkit

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/dagonet/claude-code-toolkit

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/dagonet/claude-code-toolkit

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/dagonet/claude-code-toolkit

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/dagonet/claude-code-toolkit

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/dagonet/claude-code-toolkit

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/dagonet/claude-code-toolkit

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using claude-code-toolkit with real data or production workflows.

• Configuration risk requires verification - GitHub / issue