InsForge Setup Guide for Claude Code (2026)

What It Does

InsForge is an instruction management framework for Claude Code that organizes, versions, and delivers context-engineered instructions across three channels: skills files, CLI flags, and MCP servers. Instead of scattering instructions across CLAUDE.md, ad-hoc skills, and unstructured prompts, InsForge provides a single source of truth that delivers the right instructions at the right time. This structured approach reduces context overhead by 30-50% – saving $6-$15 per month for a developer on Sonnet 4.6 ($3/$15 per MTok).

Installation / Setup

Step 1: Create the InsForge Directory Structure

mkdir -p .claude/insforge/{skills,templates,rules,hooks}

Step 2: Create the Instruction Registry

# .claude/insforge/registry.yaml
# Central registry of all instructions and their delivery channels
version: "1.0"
project: "my-project"
instructions:
  - id: "code-style"
    channel: "claude-md"
    scope: "global"
    tokens: 150
    file: "rules/code-style.md"
  - id: "deploy-procedure"
    channel: "skill"
    scope: "on-demand"
    tokens: 300
    file: "skills/deploy.md"
  - id: "db-conventions"
    channel: "skill"
    scope: "on-demand"
    tokens: 250
    file: "skills/database.md"
  - id: "test-patterns"
    channel: "directory-claude-md"
    scope: "tests/"
    tokens: 200
    file: "rules/test-patterns.md"
  - id: "api-standards"
    channel: "directory-claude-md"
    scope: "src/api/"
    tokens: 180
    file: "rules/api-standards.md"

Step 3: Create Core Instruction Files

# .claude/insforge/rules/code-style.md
# Channel: CLAUDE.md (always loaded, ~150 tokens)
## Code Style
- TypeScript strict mode, no `any` types
- Functions under 60 lines
- 2 assertions per function minimum
- Conventional commits: feat|fix|chore(scope): message

# .claude/insforge/skills/deploy.md
# Channel: skill (loaded on demand, ~300 tokens)
## Deployment Procedure
### Pre-flight Checks
1. `pnpm test` -- all tests pass
2. `pnpm build` -- no build errors
3. `git status` -- clean working tree
### Deploy to Production
1. `vercel build --prod --yes`
2. `vercel deploy --prebuilt --prod --yes`
3. `curl -sf https://example.com/health || echo "FAILED"`
### Rollback Protocol
1. `vercel rollback`
2. Verify health check passes
3. Create incident note in .claude/incidents/

# .claude/insforge/skills/database.md
# Channel: skill (loaded on demand, ~250 tokens)
## Database Conventions
- Tables: snake_case, plural
- Primary keys: `id` (uuid, generated)
- Always include: created_at, updated_at
- Soft deletes: deleted_at (nullable)
- Foreign keys: {table}_id format
## Migration Rules
- Always create reversible migrations
- Name: YYYYMMDD_HHMMSS_description.sql
- Never drop columns without 2-week deprecation

Step 4: Generate CLAUDE.md from Registry

#!/bin/bash
# .claude/insforge/generate.sh
# Builds CLAUDE.md from registry, keeping it lean
set -euo pipefail
INSFORGE_DIR=".claude/insforge"
REGISTRY="${INSFORGE_DIR}/registry.yaml"
OUTPUT="CLAUDE.md"
echo "# Project Rules" > "$OUTPUT"
echo "" >> "$OUTPUT"
echo "<!-- Generated by InsForge. Do not edit manually. -->" >> "$OUTPUT"
echo "<!-- Total token budget: 400 tokens max -->" >> "$OUTPUT"
echo "" >> "$OUTPUT"
# Include only 'claude-md' channel instructions
for rule_file in ${INSFORGE_DIR}/rules/code-style.md; do
  if [ -f "$rule_file" ]; then
    # Strip the comment header, append content
    grep -v "^# Channel:" "$rule_file" | grep -v "^# .claude" >> "$OUTPUT"
    echo "" >> "$OUTPUT"
  fi
done
# Add skill references (not full content)
echo "## Available Skills" >> "$OUTPUT"
echo "- Deploy: see deploy skill for full procedure" >> "$OUTPUT"
echo "- Database: see database skill for conventions" >> "$OUTPUT"
WORD_COUNT=$(wc -w < "$OUTPUT" | tr -d ' ')
EST_TOKENS=$((WORD_COUNT * 100 / 75))
echo ""
echo "Generated CLAUDE.md: ${WORD_COUNT} words (~${EST_TOKENS} tokens)"
if [ "$EST_TOKENS" -gt 400 ]; then
  echo "WARNING: Exceeds 400-token budget. Move content to skills."
fi

chmod +x .claude/insforge/generate.sh
.claude/insforge/generate.sh

Configuration for Cost Optimization

Token Budget Tracking

The registry tracks estimated token counts per instruction. Monitor the total:

#!/bin/bash
# .claude/insforge/audit.sh
# Reports token allocation across channels
set -uo pipefail
echo "=== InsForge Token Budget Audit ==="
GLOBAL_TOKENS=0
SKILL_TOKENS=0
DIR_TOKENS=0
# Count tokens per channel (using word count * 1.33 estimation)
for file in .claude/insforge/rules/*.md; do
  if [ -f "$file" ]; then
    WORDS=$(wc -w < "$file" | tr -d ' ')
    TOKENS=$((WORDS * 100 / 75))
    echo "  [rules] $(basename "$file"): ~${TOKENS} tokens"
    GLOBAL_TOKENS=$((GLOBAL_TOKENS + TOKENS))
  fi
done
for file in .claude/insforge/skills/*.md; do
  if [ -f "$file" ]; then
    WORDS=$(wc -w < "$file" | tr -d ' ')
    TOKENS=$((WORDS * 100 / 75))
    echo "  [skill] $(basename "$file"): ~${TOKENS} tokens (on-demand)"
    SKILL_TOKENS=$((SKILL_TOKENS + TOKENS))
  fi
done
echo ""
echo "Always-loaded (CLAUDE.md): ~${GLOBAL_TOKENS} tokens"
echo "On-demand (skills): ~${SKILL_TOKENS} tokens"
echo "Max per-session if all loaded: ~$((GLOBAL_TOKENS + SKILL_TOKENS)) tokens"
echo ""
if [ "$GLOBAL_TOKENS" -gt 400 ]; then
  echo "WARNING: Always-loaded context exceeds 400-token budget"
fi

MCP Integration for Dynamic Instructions

For instructions that depend on runtime state (environment variables, API status, database schema), InsForge can serve through a lightweight MCP server:

{
  "mcpServers": {
    "insforge": {
      "command": "node",
      "args": [".claude/insforge/mcp-server.js"],
      "env": {}
    }
  }
}

A minimal InsForge MCP server exposes a single tool that returns context-appropriate instructions:

// .claude/insforge/mcp-server.js
// Minimal MCP server for dynamic instruction delivery
const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
const fs = require("fs");
const path = require("path");
const server = new Server({ name: "insforge", version: "1.0.0" }, {
  capabilities: { tools: {} }
});
server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "get_instructions",
    description: "Get context-appropriate project instructions",
    inputSchema: {
      type: "object",
      properties: {
        task_type: { type: "string", enum: ["deploy", "database", "testing", "general"] }
      },
      required: ["task_type"]
    }
  }]
}));
server.setRequestHandler("tools/call", async (request) => {
  const taskType = request.params.arguments.task_type;
  const skillPath = path.join(__dirname, "skills", `${taskType}.md`);
  let content = "No specific instructions for this task type.";
  if (fs.existsSync(skillPath)) {
    content = fs.readFileSync(skillPath, "utf-8");
  }
  return { content: [{ type: "text", text: content }] };
});
const transport = new StdioServerTransport();
server.connect(transport);

Token cost: ~500 tokens for the tool definition, ~200-300 tokens per call. Use MCP delivery only when instructions depend on runtime state that a static skill file cannot capture.

Usage Examples

Basic Usage

After setup, InsForge instructions flow automatically:

  • CLAUDE.md rules load on every session (~150 tokens)
  • Skills load on-demand when Claude determines relevance (~250-300 tokens each)
  • MCP instructions available for runtime-dependent contexts

Advanced: Task-Specific CLI Invocation

# Deploy task: only deploy skill is relevant
claude --allowedTools "Read,Glob,Grep,Edit,Bash" \
  -p "Deploy the project to production following the deploy skill procedure"
# Database task: only database skill is relevant
claude --allowedTools "Read,Glob,Grep,Edit,Bash,mcp__insforge__get_instructions" \
  -p "Create a migration to add an 'avatar_url' column to the users table"

Token Usage Measurements

Delivery Channel Token Cost When Loaded Session Impact
CLAUDE.md rules ~150 tokens Every session Fixed overhead
Skills (on-demand) ~250-300 each When relevant Only when needed
MCP server ~500 definition + 200-300/call When configured Per-session + per-call

Without InsForge (monolithic CLAUDE.md): ~800-1,000 tokens per session (all instructions always loaded). With InsForge (progressive delivery): ~150-450 tokens per session (only relevant instructions loaded).

Savings: 400-850 tokens per session, $2.40-$5.10/month (Sonnet 4.6, 100 sessions/month).

Comparison with Alternatives

Approach Flexibility Token Efficiency Setup Effort
InsForge High High (progressive) 30 min
Monolithic CLAUDE.md Low Low (always loaded) 5 min
Ad-hoc skills Medium Medium (no governance) 10 min
Pure MCP High Low (schema overhead) 1 hour

Version Control for Instructions

InsForge instruction files should be version-controlled alongside the codebase:

# .gitignore -- do NOT ignore InsForge files
# These are part of the project's developer infrastructure
# .claude/insforge/ -- intentionally tracked
# Track changes to instructions
git add .claude/insforge/
git commit -m "chore: update deployment instructions after infra migration"

When instructions change (new deployment target, updated conventions, schema modifications), the changes are reviewed in PRs like any other code change. This prevents instruction drift where different developers have different local skill files.

Team Adoption Pattern

Rolling out InsForge across a team:

Week 1: One developer sets up InsForge, creates core instruction files
Week 2: Team reviews instruction files in a PR
Week 3: All team members pull the InsForge configuration
Week 4: Measure cost improvement with ccusage (compare pre/post InsForge sessions)

Expected adoption metrics:

  • Week 1-2: 10-20% cost reduction (core CLAUDE.md optimization)
  • Week 3-4: 25-40% cost reduction (full progressive disclosure active)
  • Month 2+: 30-50% sustained reduction (team-wide habits established)
# Track adoption effectiveness
ccusage --sort date --limit 40
# Compare average session cost before and after InsForge deployment
# Before: ~$0.45 per session (all-in-CLAUDE.md approach)
# After: ~$0.25 per session (progressive InsForge delivery)

Troubleshooting

CLAUDE.md too large after generation: Run the audit script to identify which rules exceed their token budgets. Move verbose rules to skills.

Skills not loading when expected: Ensure skill files are in .claude/skills/ (not just .claude/insforge/skills/). Create symlinks if maintaining both: ln -s ../insforge/skills/deploy.md .claude/skills/deploy.md.

MCP server not starting: Check that @modelcontextprotocol/sdk is installed in the project. Run npm install @modelcontextprotocol/sdk in the project root.

Scaling InsForge Across Multiple Projects

For organizations with multiple codebases, InsForge instruction files can be shared via a common repository:

# Shared InsForge instructions repository
git clone git@github.com:org/insforge-shared.git ~/.insforge-shared
# Symlink shared rules into each project
ln -s ~/.insforge-shared/rules/code-style.md .claude/insforge/rules/code-style.md
ln -s ~/.insforge-shared/rules/security.md .claude/insforge/rules/security.md
# Project-specific instructions stay in the project
# .claude/insforge/skills/deploy.md (project-specific)
# .claude/insforge/skills/database.md (project-specific)

This hybrid approach ensures consistent coding standards across the organization (shared rules) while allowing project-specific deployment and database conventions (local skills). The shared rules (~200 tokens) load in every project; project-specific skills (~300-500 tokens each) load only in their project.

InsForge vs Manual Skill Management

Feature InsForge Manual Skills
Token budget tracking Automated (registry) Manual counting
CLAUDE.md generation Scripted Manual editing
Skill organization Structured directories Ad-hoc
Token audit Built-in script Custom tooling
Team scaling Shared repository Copy-paste

InsForge adds 30 minutes of setup time but saves ongoing maintenance time by automating the aspects of skill management that developers otherwise neglect: token budget tracking, stale instruction cleanup, and cross-project consistency.

When InsForge Is Overkill

Not every project needs InsForge. For projects with fewer than 5 skill topics and a single developer, manual skill management is sufficient. InsForge provides value when:

  • The project has 5+ distinct operational domains (deploy, testing, database, API conventions, monitoring)
  • Multiple developers share the same instruction set
  • Token budgets need enforcement (teams spending more than $50/month on Claude Code API)
  • Cross-project consistency is required (shared coding standards across repositories)

For small personal projects with 2-3 skill files and a lean CLAUDE.md, the InsForge registry and generation scripts add complexity without proportional value. The break-even point is approximately 5 skill files and 2+ developers – below that threshold, manual management is faster and simpler.

Configure it → Build your MCP config with our MCP Config Generator.

Estimate tokens → Calculate your usage with our Token Estimator.

Try it: Paste your error into our Error Diagnostic for an instant fix.