DEV Community: pponali

Stop Wrestling with Merge Conflicts: Automate the Whole Workflow

pponali — Tue, 12 May 2026 16:08:51 +0000

It's 4:47 PM on a Friday. You've been coding all week on a feature you're proud of. You open a PR, and GitHub greets you with the one message that turns your stomach:

"This branch has conflicts that must be resolved."

You already know what's waiting. The pom.xml has diverged again. Someone on main bumped a YAML config. There are three Markdown docs with ugly <<<<<<< HEAD markers scattered through them. You're not shipping today.

Every software developer has lived this moment. And most of us keep solving it the same slow, error-prone, manual way — every single time.

This post is about why that's a problem, and how the /resolve-conflicts Claude Cowork skill fixes it — a first-class Claude skill you simply invoke in natural language, and Claude handles the entire workflow end to end.

🧩 The /resolve-conflicts skill is an installable Claude Cowork skill that automates your entire merge conflict workflow. The source code, shell script, and full documentation are open source on GitHub: github.com/pponali/claude_skills

The Real Pain Points Behind Merge Conflicts

Merge conflicts feel like a Git problem, but they're really a team coordination problem made visible. Here's what actually makes them brutal:

They always hit at the worst time. You finish a feature after days of work, go to merge, and suddenly you're debugging someone else's schema migration inside your application.yml. Context-switching mid-sprint to resolve config conflicts is a massive cognitive tax.

The same files conflict over and over. In any non-trivial project, you'll find the same suspects in your conflict list week after week: pom.xml, docker-compose.yml, *.properties, localization files, OpenAPI specs. These aren't complex logical conflicts — they're mechanical, repetitive, and boring. Yet they still demand your full attention.

Manual resolution is error-prone under pressure. When you're staring at a wall of ======= markers, it's easy to accidentally keep the wrong version, drop a dependency update, or smash together two configs in a way that silently breaks something. There's no guardrail — just you, your eyes, and your mouse.

The feedback loop is slow. You resolve conflicts, push, wait for CI, find out you introduced a bug in the config you just "fixed," fix it again, push again. The cycle can eat hours.

It doesn't scale with team size. On a small team, conflicts are annoying. On a team of 20+ engineers all merging into main frequently, they're a daily tax on every developer's time.

The Traditional Approach (And Why It Falls Short)

The standard workflow most of us follow looks like this:

git fetch origin
git merge origin/main
# ... open every conflicted file in VS Code ...
# ... manually choose ours / theirs / both ...
git add .
git commit -m "Merge branch 'main' into feature/my-thing"
git push

This works, but it has serious problems:

No consistency. Different developers make different choices for the same file types. One dev always keeps pom.xml from main; another always keeps the branch version. The merge history becomes unpredictable.
No documentation. The merge commit rarely explains why you resolved conflicts the way you did. Future you (and your teammates) have no idea.
No scalability. Every conflict requires a human to sit down and make individual decisions, even for files where the right answer is always the same.

Enter `/resolve-conflicts`: A Claude Cowork Skill That Does It All

The /resolve-conflicts skill is a Claude Cowork skill — meaning you don't run commands yourself. You just tell Claude what you want in plain English:

"Merge main into my branch and resolve conflicts"
"My PR shows conflicts — fix them"
"Sync my feature branch with origin/main"

Claude takes it from there. Under the hood it drives .claude/scripts/resolve-conflicts.sh — a shell script with codified heuristics for every file type in your project. The skill + script together are fully open source:

📦 github.com/pponali/claude_skills

The core idea: most conflicts in most projects follow predictable patterns. Once those patterns are encoded as a Claude skill, you never have to think about them again — just describe the problem and let Claude handle it.

Here's what Claude does behind the scenes when you invoke the skill:

# Step 1 — Claude runs a dry-run first and summarises what it found
.claude/scripts/resolve-conflicts.sh origin/main true

# Step 2 — After your confirmation, Claude runs for real
.claude/scripts/resolve-conflicts.sh origin/main false

Claude handles everything: stashing uncommitted changes, merging, resolving each conflict using the right heuristic, staging, creating an auditable commit, pushing, and optionally checking PR status via the gh CLI. You just review and confirm.

How the Resolution Heuristics Work

The script doesn't guess — it applies explicit, per-file-type rules:

File pattern	Strategy	Rationale
`pom.xml`, `*/pom.xml`	Keep branch (`--ours`)	Feature branch usually holds newer or WIP dependencies
`*.properties`	Keep branch	Branch has local/feature-specific config values
`.yaml` / `.yml`	Keep branch	Same reasoning as properties
`docker-compose.*`	Keep branch	Preserves the current service topology
`*.md`	Keep both (concatenated)	Docs from both sides are usually additive, not contradictory
`*.java`	Keep branch	Active feature work lives on the branch
`.js`, `.ts`, `*.tsx`	Keep branch	Same as Java
anything else	Keep branch + warning	Safe default; flagged for manual review

"Keep branch" means the HEAD side of the merge — your feature branch. The strategy is opinionated by design. If your project has different conventions, you update the script once, and every future merge follows the new rules automatically.

The Markdown strategy is particularly clever: instead of picking one side, it concatenates both. Documentation is almost always additive — two sections from different branches are usually both worth keeping, so the merge result includes both and a human can clean it up later without losing information.

The Dry-Run Is Your Best Friend

Before running for real, always do a dry run:

.claude/scripts/resolve-conflicts.sh origin/main true

The output tells you:

Which files have conflicts
Which rule the script will apply to each one
Any files in the "unknown" bucket (these get --ours by default and a warning logged)

This is the moment to catch surprises. If main bumped a critical version in pom.xml that your branch must absorb, you'll see it here. You can let the script handle everything else and manually fix just that one file afterwards.

Verify, Don't Assume

After the script runs, always check:

# Should show your merge commit
git log --oneline -3

# MUST be empty — any output here means unresolved conflicts
git diff --name-only --diff-filter=U

# Quick overview of what changed
git show HEAD --stat

If your project has a fast smoke test — mvn -q -DskipTests verify, npm run typecheck, docker compose config — run it now. Heuristic resolutions are fast but not infallible.

If you're using the gh CLI:

gh pr view <number> --json mergeable,mergeStateStatus

Note: GitHub takes 1–2 minutes to recompute mergeability after a push. Don't panic if it shows conflicts for a moment after you push.

When NOT to Use the Script

The script is great for mechanical conflicts, but there are cases where you need a human in the loop:

Core business logic in .java / .ts / .js files where both sides have unique, non-overlapping changes. The script will keep the branch version and silently drop main's changes. If both sides implemented different parts of the same feature, you need to merge them manually.

A critical dependency update in pom.xml that your branch must consume. The script keeps your branch version. After it runs, manually edit the file, git add, and git commit --amend --no-edit.

Files in the "unknown" bucket (*.sql, *.proto, *.kt, etc.). The script flags these but defaults to --ours. Open them, check if main's changes matter, resolve manually, then fold into the merge commit:

# After manually editing the file:
git add path/to/file.sql
git commit --amend --no-edit
git push --force-with-lease origin your-branch

The pattern that works best: let the script handle the 80% of mechanical conflicts, then manually patch the 20% that need actual reasoning. You get speed and correctness.

Real-World Payoff

Once your team adopts this workflow, a few things change:

Merge commits become consistent and auditable. The commit message documents which strategy was applied to which files. Six months from now, you can look at a merge commit and understand exactly what happened.

Conflict resolution stops being a senior-developer task. The rules are encoded in a script, not in someone's head. A junior developer can merge safely without needing to ask "should I keep ours or theirs for the YAML?".

Friday afternoon PRs stop being feared. When conflict resolution is one command instead of a half-hour of careful manual editing, you stop dreading the merge.

Getting Started: Install the Claude Skill

Everything — the skill definition, the shell script, and full documentation — is in the open source repo:

📦 github.com/pponali/claude_skills

# Add the script to your project
mkdir -p .claude/scripts
curl -o .claude/scripts/resolve-conflicts.sh \
  https://raw.githubusercontent.com/pponali/claude_skills/master/.claude/scripts/resolve-conflicts.sh
chmod +x .claude/scripts/resolve-conflicts.sh

Once installed, just open Claude in Cowork mode and describe the problem. Claude will:

Run pre-flight checks (detects if you're already mid-merge)
Do a dry run and summarise exactly which files it will touch and how
Ask for your confirmation before committing anything
Merge, resolve, commit, push — and report back

You're always in control. Claude handles the mechanical parts, you handle the judgment calls.

Running the script directly (without Claude) is also supported:

# Dry run first — always
.claude/scripts/resolve-conflicts.sh origin/main true

# Then for real
.claude/scripts/resolve-conflicts.sh origin/main false

# Merge a different branch
.claude/scripts/resolve-conflicts.sh origin/feat/payment false

The Full Script

Drop this into .claude/scripts/resolve-conflicts.sh in your repo and make it executable (chmod +x). It's self-contained — no external dependencies beyond bash, git, and optionally the gh CLI for PR status checks.

#!/usr/bin/env bash
# =============================================================================
# resolve-conflicts.sh
# Automated merge-conflict resolution with per-file-type heuristics.
#
# Usage:
#   .claude/scripts/resolve-conflicts.sh [target-branch] [dry-run]
#
# Arguments:
#   target-branch  Branch to merge in. Default: origin/main
#   dry-run        true|false. Default: false
#
# Examples:
#   .claude/scripts/resolve-conflicts.sh                          # merge origin/main, for real
#   .claude/scripts/resolve-conflicts.sh origin/main true        # dry-run first
#   .claude/scripts/resolve-conflicts.sh origin/feat/payment false
# =============================================================================

set -euo pipefail

TARGET_BRANCH="${1:-origin/main}"
DRY_RUN="${2:-false}"

# Colour helpers
RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'; CYAN='\033[0;36m'; NC='\033[0m'
info()    { echo -e "${CYAN}[resolve-conflicts]${NC} $*"; }
success() { echo -e "${GREEN}[resolve-conflicts]${NC} $*"; }
warn()    { echo -e "${YELLOW}[resolve-conflicts] WARN:${NC} $*"; }
error()   { echo -e "${RED}[resolve-conflicts] ERROR:${NC} $*" >&2; }

# ---------------------------------------------------------------------------
# Pre-flight
# ---------------------------------------------------------------------------
if git rev-parse --verify MERGE_HEAD &>/dev/null; then
  error "Repo is already mid-merge (MERGE_HEAD exists)."
  error "Run 'git merge --abort' to cancel the previous merge, then retry."
  exit 1
fi

CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
info "Current branch : $CURRENT_BRANCH"
info "Target branch  : $TARGET_BRANCH"
info "Dry run        : $DRY_RUN"

info "Fetching origin..."
git fetch origin --quiet

# ---------------------------------------------------------------------------
# Stash any uncommitted changes
# ---------------------------------------------------------------------------
STASHED=false
if ! git diff --quiet || ! git diff --cached --quiet; then
  info "Stashing local changes..."
  git stash push -m "resolve-conflicts auto-stash $(date +%s)"
  STASHED=true
fi

# ---------------------------------------------------------------------------
# Attempt the merge
# ---------------------------------------------------------------------------
info "Merging $TARGET_BRANCH into $CURRENT_BRANCH..."
if git merge "$TARGET_BRANCH" --no-edit --no-commit 2>/dev/null; then
  success "Merge completed with no conflicts. Committing..."
  if [ "$DRY_RUN" = "false" ]; then
    git commit --no-edit -m "Merge $TARGET_BRANCH into $CURRENT_BRANCH (no conflicts)"
    git push origin "$CURRENT_BRANCH"
    success "Pushed."
  else
    git merge --abort 2>/dev/null || true
    info "[DRY RUN] No conflicts — merge would succeed cleanly."
  fi
  $STASHED && git stash pop || true
  exit 0
fi

CONFLICTED_FILES="$(git diff --name-only --diff-filter=U)"

if [ -z "$CONFLICTED_FILES" ]; then
  warn "Merge stopped but no conflict markers found. Check git status."
  git merge --abort 2>/dev/null || true
  $STASHED && git stash pop || true
  exit 1
fi

info "Conflicted files:"
echo "$CONFLICTED_FILES" | while read -r f; do echo "  - $f"; done

# ---------------------------------------------------------------------------
# Resolution heuristics
# ---------------------------------------------------------------------------
resolve_file() {
  local file="$1"
  local strategy="" reason=""

  case "$file" in
    pom.xml|*/pom.xml)
      strategy="ours";  reason="pom.xml — keep branch (feature deps)" ;;
    *.properties)
      strategy="ours";  reason="*.properties — keep branch (feature config)" ;;
    *.yaml|*.yml)
      strategy="ours";  reason="*.yaml/yml — keep branch (feature config)" ;;
    docker-compose*|*/docker-compose*)
      strategy="ours";  reason="docker-compose — keep branch (feature topology)" ;;
    *.md)
      strategy="union"; reason="*.md — keep both (documentation is additive)" ;;
    *.java)
      strategy="ours";  reason="*.java — keep branch (active feature work)" ;;
    *.js|*.ts|*.tsx|*.jsx)
      strategy="ours";  reason="*.js/ts — keep branch (active feature work)" ;;
    *)
      strategy="ours"
      reason="unknown type — defaulting to branch; MANUAL REVIEW RECOMMENDED"
      warn "No rule for: $file — keeping branch version. Please verify manually." ;;
  esac

  if [ "$DRY_RUN" = "true" ]; then
    info "[DRY RUN] $file → $strategy  ($reason)"
    return
  fi

  info "Resolving: $file → $strategy  ($reason)"

  if [ "$strategy" = "ours" ]; then
    git checkout --ours -- "$file"
    git add "$file"
  elif [ "$strategy" = "union" ]; then
    local ours theirs
    ours="$(git show :2:"$file" 2>/dev/null || true)"
    theirs="$(git show :3:"$file" 2>/dev/null || echo "")"
    { echo "$ours"; echo ""; echo "---"; echo "<!-- merged from $TARGET_BRANCH -->"; echo ""; echo "$theirs"; } > "$file"
    git add "$file"
  fi
}

while IFS= read -r file; do
  [ -n "$file" ] && resolve_file "$file"
done <<< "$CONFLICTED_FILES"

# ---------------------------------------------------------------------------
# Commit and push
# ---------------------------------------------------------------------------
if [ "$DRY_RUN" = "true" ]; then
  info "[DRY RUN] Complete. No files were changed."
  git merge --abort 2>/dev/null || true
  $STASHED && git stash pop || true
  exit 0
fi

STILL_CONFLICTED="$(git diff --name-only --diff-filter=U 2>/dev/null || true)"
if [ -n "$STILL_CONFLICTED" ]; then
  error "Some files are still unresolved — resolve manually, 'git add', then 'git commit'."
  echo "$STILL_CONFLICTED"
  $STASHED && git stash pop || true
  exit 1
fi

COMMIT_MSG="Merge $TARGET_BRANCH into $CURRENT_BRANCH (auto-resolved)

Heuristics applied:
$(echo "$CONFLICTED_FILES" | while read -r f; do echo "  - $f"; done)

Generated by resolve-conflicts.sh"

git commit -m "$COMMIT_MSG"
success "Merge commit created."

git push origin "$CURRENT_BRANCH"
success "Pushed to origin/$CURRENT_BRANCH."

if $STASHED; then
  info "Restoring stashed changes..."
  git stash pop || warn "Stash pop failed — run 'git stash list' to inspect."
fi

if command -v gh &>/dev/null; then
  info "Checking PR status (GitHub may take ~2 min to recompute)..."
  gh pr view --json mergeable,mergeStateStatus 2>/dev/null \
    | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'  mergeable={d[\"mergeable\"]}  state={d[\"mergeStateStatus\"]}')" \
    || true
fi

success "Done. Run 'git log --oneline -3' to verify the merge commit."

Save it, make it executable, and you're ready:

mkdir -p .claude/scripts
# paste the script above into .claude/scripts/resolve-conflicts.sh
chmod +x .claude/scripts/resolve-conflicts.sh

Merge conflicts aren't going away. As long as multiple people work on the same codebase, there will be divergence. But the amount of manual, repetitive work they require is entirely within your control. Codify your team's conventions, automate the mechanics, and save the human judgment for the conflicts that actually need it.

Your future Friday self will thank you.

Circuit Breakers Under Stress: Anatomy of a Payment Cascade

pponali — Sun, 10 May 2026 14:10:46 +0000

A flash sale hit us at 10x baseline RPS. Within four minutes, our Payment Service circuit breaker tripped to OPEN, error rate climbed to 92%, and p99 latency on the payment path went from 200ms to 14.2 seconds. Here's the part nobody tells you on the conference circuit: the circuit breaker didn't fail. It worked exactly as designed. The failure was everywhere else.

This is a postmortem of what we saw, why Resilience4j's defaults weren't enough, and the four changes that made the next sale boring.

The setup

Standard Java microservices stack. Spring Cloud Gateway in front, JWT auth via Keycloak, Resilience4j wrapping every outbound call. Payment Service synchronously calls Stripe. Order Service synchronously calls Payment. PostgreSQL for orders, Redis for circuit breaker state, Kafka for the dead-letter queue.

Six services. Five circuit breakers. One very stressed thread pool.

What 10x RPS actually does

Baseline was around 1,000 RPS. The flash sale pushed us to 10,243. The edge layer absorbed it fine — NGINX did its job, the rate limiter degraded gracefully, the CDN cached anything cacheable. Spring Cloud Gateway routed cleanly.

The wheels came off at the Payment Service. Stripe's p99 latency under load climbed from a healthy 800ms to 14.2 seconds. That doesn't sound catastrophic until you do the math: every Payment thread now holds for ~14s instead of <1s. With a fixed thread pool, throughput collapses long before the breaker notices.

# What we had — Resilience4j defaults, lightly tuned
resilience4j.circuitbreaker:
  instances:
    paymentService:
      failureRateThreshold: 50
      slidingWindowSize: 100
      slidingWindowType: COUNT_BASED
      waitDurationInOpenState: 30s
      permittedNumberOfCallsInHalfOpenState: 10

A 50% failure threshold over 100 calls means the breaker waits for 50 failures before tripping. At 10x load with timeouts, that's roughly four minutes of users staring at spinners. By the time the breaker opened, the thread pool was already 98% saturated.

The cascade, step by step

The order matters:

Flash-sale spike hits the gateway at 10x RPS.
Order Service synchronously calls Payment for every checkout.
Stripe's p99 spikes to 14s under provider-side load.
Payment Service threads block on those timeouts.
failureRateThreshold=50% breached → Payment CB transitions to OPEN.
Subsequent calls fail-fast → fallback handler enqueues "deferred order" responses to Kafka.
Order Service's own CB drops to HALF-OPEN, probing with limited concurrency.
Bulkhead isolation prevents the cascade from reaching Inventory, Notifications, or User services.

Step 8 is the only reason this incident wasn't a full-platform outage. Without per-endpoint bulkheads, a slow Stripe would have eaten every thread in the gateway's pool, and User Service login requests would have queued behind dead Payment calls.

The state machine, practically

If you've only read the docs, the circuit breaker looks like a tidy three-state diagram. In production it's noisier:

// Resilience4j state transitions, simplified
CircuitBreaker cb = CircuitBreaker.of("paymentService", config);

cb.getEventPublisher()
  .onStateTransition(event -> {
      log.warn("CB {} : {} -> {}",
          event.getCircuitBreakerName(),
          event.getStateTransition().getFromState(),
          event.getStateTransition().getToState());
      meterRegistry.counter("cb.transition",
          "name", event.getCircuitBreakerName(),
          "to", event.getStateTransition().getToState().name()
      ).increment();
  });

That listener saved us during the postmortem. We could replay exactly when each breaker tripped, when probing started, and which trial calls failed. If you don't emit metrics on every state transition, you're flying blind.

The HALF-OPEN state is the dangerous one. Resilience4j permits a small number of trial calls; if any of them fail, you slam back to OPEN for another waitDuration. Set the trial pool too low and you'll never recover; set it too high and you'll hammer a still-broken downstream.

Four changes that fixed it

1. Tighter, faster breakers

We dropped the threshold and shrunk the window:

resilience4j.circuitbreaker:
  instances:
    paymentService:
      failureRateThreshold: 30          # was 50
      slowCallRateThreshold: 50          # NEW — slow calls also count
      slowCallDurationThreshold: 2s      # NEW
      slidingWindowSize: 20              # was 100
      minimumNumberOfCalls: 10
      waitDurationInOpenState: 15s       # was 30s
      permittedNumberOfCallsInHalfOpenState: 5

Two non-obvious knobs matter here. slowCallRateThreshold lets you trip on latency, not just errors — critical when a downstream is dying slowly rather than 500-ing. And the smaller window means the breaker reacts in seconds, not minutes.

2. Per-endpoint bulkheads

A single thread pool for "Payment Service" is too coarse. Split by downstream:

@Bean
public ThreadPoolBulkhead stripeBulkhead() {
    ThreadPoolBulkheadConfig config = ThreadPoolBulkheadConfig.custom()
        .maxThreadPoolSize(20)
        .coreThreadPoolSize(10)
        .queueCapacity(50)
        .keepAliveDuration(Duration.ofMillis(500))
        .build();
    return ThreadPoolBulkhead.of("stripe", config);
}

@Bean
public ThreadPoolBulkhead fraudBulkhead() {
    // Smaller — fraud is allowed to be slow, not allowed to starve payment
    return ThreadPoolBulkhead.of("fraud",
        ThreadPoolBulkheadConfig.custom()
            .maxThreadPoolSize(8)
            .coreThreadPoolSize(4)
            .build());
}

Now a slow fraud engine can't drain Stripe's threads, and vice versa. Bulkhead-per-dependency is more YAML, but it's the only way to guarantee isolation when one downstream misbehaves.

3. Async outbox + Kafka retry

The synchronous Order → Payment → Stripe chain was the real sin. We moved Payment to an outbox pattern: orders write a payment intent to Postgres in the same transaction, a relay publishes to Kafka, and a worker calls Stripe asynchronously. The user gets an immediate "order placed" response; the charge happens within seconds, with retries handled by the consumer.

@Transactional
public Order placeOrder(OrderRequest req) {
    Order order = orderRepo.save(Order.from(req));
    outboxRepo.save(new OutboxEvent(
        "payment.charge.requested",
        order.getId(),
        objectMapper.writeValueAsString(req.payment())
    ));
    return order;  // returns in <50ms regardless of Stripe latency
}

Decoupling time-of-order from time-of-charge means a 14-second Stripe doesn't translate to a 14-second user experience. It also gives us natural retry and dead-lettering through Kafka, instead of bolting retry logic onto every caller.

4. HPA on RPS and queue depth

The Payment Service was scaled on CPU, which is useless when threads are blocked on I/O. We swapped to a custom Prometheus metric — RPS plus Kafka consumer lag — and let the HPA add pods when the queue grew faster than it drained. CPU never crossed 40% during the incident; if we'd been watching the right signal, we'd have scaled out three minutes earlier.

What I'd tell past me

The circuit breaker is a fire alarm, not a fire suppression system. By the time it trips, you've already had a fire for a while. The real defenses are the things that stop the fire from starting: bulkhead isolation per downstream, slow-call detection, async boundaries on anything you don't fully control, and autoscaling on signals that actually correlate with load.

Resilience4j is excellent. The defaults are not your friend in production.

Takeaways

If you take three things from this:

Trip on latency, not just errors. slowCallRateThreshold is the most underused knob in Resilience4j.
One bulkhead per downstream, always. Coarse pools will betray you the moment two dependencies fail differently.
Synchronous chains across third-party APIs are tech debt. An outbox + queue is more code, but it's the difference between a postmortem and an incident report.

The next flash sale ran 12x baseline. Payment p99 stayed under 600ms. Nobody paged.

After the Skill Vault: 3 More Hidden Token Sinks in Claude Code

pponali — Fri, 08 May 2026 00:48:13 +0000

If you read my earlier post on the Skill Vault pattern, you know I cut Claude Code's per-session overhead by 96%. After living with it for a few weeks, I went looking for what was still eating tokens — and found three more sinks worth killing.

This is the follow-up: smaller wins individually, but together they shaved another ~5,000 tokens off every single session with zero capability lost.

Where the Tokens Were Still Hiding

After the vault, my baseline was around 51K tokens per session. I dug into the system prompt to see what remained:

Skill list (still): ~3K tokens
Project CLAUDE.md: ~2K tokens
claude-mem auto-injected timeline: ~2K tokens
Plugin hook reminders: ~1K tokens (some recurring per turn)

Three of these were either unnecessary or way overweight. Here's how I killed each.

Sink #1: A Bloated Root CLAUDE.md (~1.5K tokens)

CLAUDE.md files auto-load into every session that touches the repo. Mine had grown to 326 lines / 8 KB with quickstart instructions for every component:

Flutter dev commands
Backend npm scripts
React build steps
ML service Python setup
A duplicate gstack skill listing

The problem: I was loading every component's instructions on every turn, even when I was only working in one of them.

Fix: Hierarchical CLAUDE.md Files

Claude Code loads CLAUDE.md hierarchically — only the ones in your current working tree get pulled in. So instead of one fat root file, I split it:

khetisahayak/
├── CLAUDE.md                    # 55 lines — overview, ports, creds only
├── kheti_sahayak_app/CLAUDE.md  # Flutter details
├── frontend/CLAUDE.md           # React details
├── ml/CLAUDE.md                 # ML service details
└── kheti_sahayak_backend/CLAUDE.md  # already existed

The root now contains only:

Project overview (5 lines)
Service ports table
Test credentials
Cross-cutting auth + DB notes
Troubleshooting

Component-specific details only load when I'm actually working in that subdir.

Result: root CLAUDE.md trimmed from 326 → 55 lines (8 KB → 1.6 KB). ~1.5K tokens saved per session.

Sink #2: Plugin SessionStart Hooks Injecting "Helpful" Context

I use claude-mem for persistent memory across sessions. Genuinely useful. But it has a SessionStart hook that auto-injects a timeline of recent observations at the top of every conversation — about 50 entries, ~2K tokens:

S499 Indeed Auto-Apply — User asked how to automate job applications
S498 Indeed MCP Integration Query — clarifying JobSpy vs Apify
2337 12:33p ✅ systemd/install.sh — Backend Services Enabled
... 47 more lines

I almost never needed this auto-recall. When I want past context, I call mem-search explicitly.

Fix: Disable the Auto-Inject, Keep the Memory

The hook config lives at:

~/.claude/plugins/cache/thedotmack/claude-mem/<version>/hooks/hooks.json

The SessionStart array has three hooks. The third is the timeline injection:

{
  "type": "command",
  "command": "... node bun-runner.js worker-service.cjs hook claude-code context ..."
}

I removed just that one entry. The other two SessionStart hooks (install + worker-start) and the recording hooks (PostToolUse, Stop, SessionEnd) stay intact, so memory is still being captured. The MCP search server still works — I just have to ask for it.

# Always back up before editing plugin internals
cp hooks.json hooks.json.bak
# Remove the 3rd SessionStart hook (jq or manual edit)

Result: ~2K tokens saved per session. Memory still works on demand.

⚠️ Caveat: editing a file in ~/.claude/plugins/cache/ will be overwritten on plugin upgrade. For durability, mirror the change in your user-level ~/.claude/settings.json hooks block, or add a small post-upgrade re-patch script.

Sink #3: Round 2 of the Skill Vault (~1.4K tokens)

The original vault was a one-time bulk move. After several weeks of actual usage, I saw which skills I'd installed and never touched. The vault was overdue for a second pass.

Audit script (same as the first post, run again):

for f in ~/.claude/skills/*/SKILL.md; do
  dir=$(dirname "$f")
  name=$(basename "$dir")
  size=$(wc -c < "$f")
  echo "$size $name"
done | sort -rn | head -30

I ended up vaulting 27 more skills out of 73 actively loaded:

8 marketing skills (mkt-content, mkt-seo, mkt-social, etc.) — I do real marketing in a separate context
6 research skills (research, research-deep, research-report, etc.) — episodic, not daily
5 niche tools (obsidian-vault, make-pdf, pair-agent, setup-browser-cookies, open-gstack-browser)
4 design-heavy (design-consultation, design-html, design-shotgun, devex-review) — restored only when designing
3 plan reviews (plan-design-review, plan-devex-review, plan-tune)
1 interview prep (staff-engineer-interview) — used a few times last quarter, not weekly

Bulk move:

for s in mkt-content mkt-email mkt-growth mkt-pr mkt-review mkt-seo mkt-social cmo \
         research research-add-fields research-add-items research-deep research-report edit-article \
         staff-engineer-interview \
         obsidian-vault make-pdf pair-agent setup-browser-cookies open-gstack-browser \
         plan-design-review plan-devex-review plan-tune \
         design-consultation design-html design-shotgun devex-review; do
  mv ~/.claude/skills/$s ~/.claude/skills-vault/ 2>/dev/null
done

The skill-vault index skill from the original post still bridges everything — Claude knows where each skill lives and restores it on demand.

Result: 73 → 46 active skills. ~1.4K tokens saved.

The Combined Result

Fix	Tokens Saved (per session)
Sink #1 — CLAUDE.md trim + per-component split	~1.5K
Sink #2 — claude-mem timeline disabled	~2K
Sink #3 — Round 2 skill vault	~1.4K
Total	~4.9K

On top of the original 96% reduction from the Skill Vault, this is another solid bite. But honestly, the dollar value isn't the point.

Why This Matters Beyond Cost

Every token in your context is a token Claude has to attend over before generating its response. The bigger your prompt, the more diluted attention becomes on the actual task.

Big context ≠ better answers. Frequently it's the opposite. Targeted context wins.

The pattern across all three fixes is the same:

Audit what's auto-loaded vs. what's actually useful. You'll be surprised.
Move episodic content out of the always-on path and into on-demand access.
Trust the model to pull what it needs — when it does need the vaulted skill, the subdir's CLAUDE.md, or the memory search, it will reach for it.

Less ambient noise. Sharper signal.

Tips for Your Own Audit

Inspect, don't guess. wc -c your CLAUDE.md files. ls ~/.claude/skills/. Read your plugin hooks.json files line by line.
Hierarchy is free. Per-directory CLAUDE.md files cost nothing when you're not in that directory.
Plugin hooks are debt. Every SessionStart or UserPromptSubmit hook is a tax. Audit them by hand. Some are essential (auth, telemetry); some inject "context" that's just clutter.
Re-vault every few weeks. Usage patterns shift. Skills that were daily three months ago may be quarterly now. Yesterday's must-have is tomorrow's vault candidate.
Watch for per-turn taxes. A UserPromptSubmit hook costs N tokens every single turn. Even a small reminder block adds up fast in a long session.

Conclusion

The Skill Vault pattern is still the heaviest hitter. These three follow-ups are the long tail:

CLAUDE.md → split per component, slim the root.
Plugin hooks → audit auto-injected context. Disable what you don't need.
Skill vault → revisit it. Vault more.

Together: another ~5K tokens per session, zero capability lost.

When your context is tight, your model is sharp.

I'm Prakash Ponali, a Staff Engineer with 16+ years in enterprise eCommerce. Currently building Khetisahayak — a farming helper app for Telugu-speaking farmers in Andhra Pradesh. Find me on LinkedIn.

How I Cut Claude Code Token Consumption by 96% with the Skill Vault Pattern

pponali — Sun, 19 Apr 2026 07:45:04 +0000

The Problem: 181 Skills Burning 1.18 Million Tokens Per Session

I'm a power user of Claude Code — Anthropic's CLI for AI-assisted development. Over weeks of installing skill packs from GitHub repos, I accumulated 181 skills from multiple sources:

gstack agents (QA, design, deploy, monitoring)
marketingskills by Corey Haines (36 CRO/SEO/copywriting skills)
wondelai/skills (42 product/engineering frameworks)
superpowers by obra (14 dev methodology skills)
claude-mem (persistent memory plugin)
Deep-Research-skills (structured research workflows)
Custom skills I built myself

Sounds great, right? More skills = more capability.

Wrong. Every new conversation, Claude Code injects ALL skill descriptions into the system prompt. With 181 skills, that's approximately 1.18 million tokens of overhead per session — before I even type my first message.

Tokens were burning like a wildfire. Every task was expensive. Context windows were filling up fast.

The Discovery: Measuring the Actual Cost

I ran a simple audit to see exactly what was happening:

# Count total SKILL.md bytes across all skills
total=0
for f in ~/.claude/skills/*/SKILL.md; do
  size=$(wc -c < "$f" 2>/dev/null)
  total=$((total + size))
done
echo "Total bytes: $total"
echo "Approx tokens: $((total / 4))"

Result: 4.7MB of SKILL.md files = ~1.18 million tokens.

The top offenders were massive:

Skill	Size	Tokens
ship (gstack)	130KB	~32K
plan-ceo-review	112KB	~28K
office-hours	101KB	~25K
seedance-15-real-estate	95KB	~24K
plan-devex-review	93KB	~23K

15 Seedance video skills alone consumed ~265K tokens. I used them maybe once a month.

The Solution: The Skill Vault Pattern

The idea is simple:

Move rarely-used skills to a vault directory (out of auto-load)
Keep a lightweight index skill that tells Claude what's available
Claude restores skills on-demand when your request matches one
Optionally move it back after the task

Step 1: Create the Vault

mkdir -p ~/.claude/skills-vault

Step 2: Audit Your Skills by Usage Frequency

Sort all skills by file size to find the biggest offenders:

for f in ~/.claude/skills/*/SKILL.md; do
  dir=$(dirname "$f")
  name=$(basename "$dir")
  size=$(wc -c < "$f")
  echo "$size $name"
done | sort -rn | head -30

Then categorize them:

Tier 1 (Daily use): Keep active — your core dev workflow skills
Tier 2 (Project-specific): Keep active — skills tied to current projects
Tier 3 (Occasional): Vault — heavy skills used weekly/monthly
Tier 4 (Rare): Vault — frameworks and reference skills

Step 3: Move Skills to the Vault

# Move video generation skills (rarely used)
mv ~/.claude/skills/seedance-* ~/.claude/skills-vault/

# Move heavy plan review skills
mv ~/.claude/skills/{plan-ceo-review,plan-eng-review,plan-design-review} \
   ~/.claude/skills-vault/

# Move framework/reference skills
mv ~/.claude/skills/{clean-architecture,domain-driven-design,system-design} \
   ~/.claude/skills-vault/

# Move marketing skills you don't use daily
mv ~/.claude/skills/{copywriting,seo-audit,paid-ads,cold-email} \
   ~/.claude/skills-vault/

Step 4: Create the Index Skill (The Key Ingredient)

This is what makes the pattern work. Create a lightweight skill that acts as a lookup table for Claude:

mkdir -p ~/.claude/skills/skill-vault

Create ~/.claude/skills/skill-vault/SKILL.md:

---
name: skill-vault
description: Index of vaulted skills at ~/.claude/skills-vault/.
  When the user's request matches a vaulted skill, restore it with
  mv ~/.claude/skills-vault/<name> ~/.claude/skills/ then use it.
  Use when user asks about design, SEO, CRO, copywriting,
  architecture patterns, security audit, deployment, video
  generation, or any topic not covered by active skills.
---

## Skill Vault

Skills stored in `~/.claude/skills-vault/` to save tokens.
When a user request matches one, restore it:

mv ~/.claude/skills-vault/<skill-name> ~/.claude/skills/

Then invoke it normally. After the task, optionally move back:

mv ~/.claude/skills/<skill-name> ~/.claude/skills-vault/

## Vaulted Skills Index

### Design & UI
- `design-review` — Visual QA, spacing/hierarchy fixes
- `design-html` — Production HTML/CSS from mockups
- `design-shotgun` — Generate multiple design variants
- `top-design` — Awwwards-quality web experiences

### Engineering Frameworks
- `clean-architecture` — Dependency rule, ports/adapters
- `domain-driven-design` — Bounded contexts, aggregates
- `system-design` — Distributed systems, scaling
- `refactoring-patterns` — Extract method, code smells

### DevOps & Monitoring
- `land-and-deploy` — Merge, CI, verify production
- `canary` — Post-deploy monitoring
- `cso` — Security audit (OWASP, STRIDE)

### Marketing
- `copywriting` — Marketing copy for any page
- `seo-audit` — Technical SEO audit
- `paid-ads` — Google/Meta/LinkedIn campaigns

(... add all your vaulted skills here ...)

This index costs only ~1.5K tokens but gives Claude awareness of all 139 vaulted skills.

The Results

Metric	Before	After	Reduction
Active skills	181	43	76% fewer
Tokens per session	~1.18M	~51K	96%
Vaulted (on-demand)	0	139	—
Capability lost	—	None	0%

96% token reduction with zero capability loss.

How It Works at Runtime

You: "audit my design for visual issues"

Claude thinks:
  1. No active skill matches "design audit"
  2. skill-vault index matches: design-review
  3. Run: mv ~/.claude/skills-vault/design-review ~/.claude/skills/
  4. Now use design-review skill normally
  5. Task complete

Claude reads the vault index, finds the right skill, restores it with a single mv command, and proceeds normally. The user experience is seamless.

My Final Active Skill Set (43 Skills)

Here's what I kept always-active:

Core Dev Workflow (Superpowers):
ship, qa, browse, review, investigate, writing-plans, executing-plans, brainstorming, subagent-driven-development, systematic-debugging, test-driven-development, verification-before-completion

Project-Specific:
ecommerce-architect, staff-engineer-interview, claude-api-patterns, claude-code-mastery, mcp-server-development

Marketing (Khetisahayak):
cmo, mkt-content, mkt-seo, mkt-social, mkt-growth, mkt-email, mkt-pr, mkt-review

Research:
research, research-deep, research-report

The Vault Index:
skill-vault (the 1.5K token index that knows about 139 other skills)

Tips for Your Own Vault

Audit first. Run the size audit script before moving anything. You might be surprised which skills are the heaviest.
Keep your daily drivers active. Don't vault skills you use every session. The restore step adds a small delay.
Group by category. Makes it easy to restore a whole category:

   mv ~/.claude/skills-vault/seedance-* ~/.claude/skills/

Update the index when you add new skills to the vault.
Restore everything if you need full power for a complex session:

   mv ~/.claude/skills-vault/* ~/.claude/skills/

Where to Find Great Skills

Here are the skill repos I installed from:

marketingskills — 36 marketing skills by Corey Haines
wondelai/skills — 42 product/engineering framework skills
obra/superpowers — Dev methodology (TDD, planning, subagents)
Deep-Research-skills — Structured research workflows
claude-mem — Persistent memory across sessions

Installing is simple — symlink into ~/.claude/skills/:

git clone https://github.com/coreyhaines31/marketingskills.git
for skill_dir in marketingskills/skills/*/; do
  ln -s "$(pwd)/$skill_dir" ~/.claude/skills/$(basename "$skill_dir")
done

Then vault what you don't need daily.

Conclusion

The Skill Vault pattern is dead simple:

~/.claude/skills/ = active skills (loaded every turn)
~/.claude/skills-vault/ = dormant skills (restored on demand)
skill-vault/SKILL.md = lightweight index that bridges the two

If you're running more than 50 skills in Claude Code, you're probably burning hundreds of thousands of unnecessary tokens per session. The vault pattern gives you the full arsenal without the cost.

96% fewer tokens. Zero lost capability. One mv command away.

Web Topic Analysis Report - 2025-07-19

pponali — Sat, 19 Jul 2025 14:53:45 +0000

Web Topic Analysis Report - 2025-07-19

By AI Content Generator on July 19, 2025

Tags: web_analysis, tech_trends, ai_analysis

Web Topic Analysis Report

Workflow ID: web_topic_analysis_20250719_145337
Generated: 2025-07-19T14:53:37.277540

No analysis results available.

Web Topic Analysis Report - 2025-07-19

pponali — Sat, 19 Jul 2025 14:34:12 +0000

Web Topic Analysis Report - 2025-07-19

By AI Content Generator on July 19, 2025

Tags: web_analysis, tech_trends, ai_analysis

Web Topic Analysis Report

Workflow ID: web_topic_analysis_20250719_143346
Generated: 2025-07-19T14:33:46.400427

No analysis results available.

Web Topic Analysis Report - 2025-07-19

pponali — Sat, 19 Jul 2025 11:00:37 +0000

Web Topic Analysis Report - 2025-07-19

By AI Content Generator on July 19, 2025

Tags: web_analysis, tech_trends, ai_analysis

Web Topic Analysis Report

Workflow ID: web_topic_analysis_20250719_110024
Generated: 2025-07-19T11:00:24.674147

No analysis results available.

Web Topic Analysis Report - 2025-07-19

pponali — Sat, 19 Jul 2025 10:55:14 +0000

Web Topic Analysis Report - 2025-07-19

By AI Content Generator on July 19, 2025

Tags: web_analysis, tech_trends, ai_analysis

Web Topic Analysis Report

Workflow ID: web_topic_analysis_20250719_105459
Generated: 2025-07-19T10:54:59.752185

No analysis results available.

Web Topic Analysis Report - 2025-07-19

pponali — Sat, 19 Jul 2025 10:47:55 +0000

Web Topic Analysis Report - 2025-07-19

By AI Content Generator on July 19, 2025

Tags: web_analysis, tech_trends, ai_analysis

Web Topic Analysis Report

Workflow ID: web_topic_analysis_20250719_104730
Generated: 2025-07-19T10:47:30.038257

No analysis results available.

Web Topic Analysis Report - 2025-07-19

pponali — Sat, 19 Jul 2025 10:26:53 +0000

Web Topic Analysis Report - 2025-07-19

By AI Content Generator on July 19, 2025

Tags: web_analysis, tech_trends, ai_analysis

Web Topic Analysis Report

Workflow ID: web_topic_analysis_20250719_102641
Generated: 2025-07-19T10:26:41.742468

No analysis results available.

Web Topic Analysis Report - 2025-07-19

pponali — Sat, 19 Jul 2025 09:05:44 +0000

Web Topic Analysis Report - 2025-07-19

By AI Content Generator on July 19, 2025

Tags: web_analysis, tech_trends, ai_analysis

Web Topic Analysis Report

Workflow ID: web_topic_analysis_20250719_090536
Generated: 2025-07-19T09:05:36.038055

No analysis results available.

Web Topic Analysis Report - 2025-07-19

pponali — Sat, 19 Jul 2025 08:13:14 +0000

Web Topic Analysis Report - 2025-07-19

By AI Content Generator on July 19, 2025

Tags: web_analysis, tech_trends, ai_analysis

Web Topic Analysis Report

Workflow ID: web_topic_analysis_20250719_081303
Generated: 2025-07-19T08:13:03.675446

No analysis results available.

DEV Community: pponali

Stop Wrestling with Merge Conflicts: Automate the Whole Workflow

The Real Pain Points Behind Merge Conflicts

The Traditional Approach (And Why It Falls Short)

Enter /resolve-conflicts: A Claude Cowork Skill That Does It All

How the Resolution Heuristics Work

The Dry-Run Is Your Best Friend

Verify, Don't Assume

When NOT to Use the Script

Real-World Payoff

Getting Started: Install the Claude Skill

The Full Script

Circuit Breakers Under Stress: Anatomy of a Payment Cascade

The setup

What 10x RPS actually does

The cascade, step by step

The state machine, practically

Four changes that fixed it

1. Tighter, faster breakers

2. Per-endpoint bulkheads

3. Async outbox + Kafka retry

4. HPA on RPS and queue depth

What I'd tell past me

Takeaways

After the Skill Vault: 3 More Hidden Token Sinks in Claude Code

Where the Tokens Were Still Hiding

Sink #1: A Bloated Root CLAUDE.md (~1.5K tokens)

Fix: Hierarchical CLAUDE.md Files

Sink #2: Plugin SessionStart Hooks Injecting "Helpful" Context

Fix: Disable the Auto-Inject, Keep the Memory

Sink #3: Round 2 of the Skill Vault (~1.4K tokens)

The Combined Result

Why This Matters Beyond Cost

Tips for Your Own Audit

Conclusion

How I Cut Claude Code Token Consumption by 96% with the Skill Vault Pattern

The Problem: 181 Skills Burning 1.18 Million Tokens Per Session

The Discovery: Measuring the Actual Cost

The Solution: The Skill Vault Pattern

Step 1: Create the Vault

Step 2: Audit Your Skills by Usage Frequency

Step 3: Move Skills to the Vault

Step 4: Create the Index Skill (The Key Ingredient)

The Results

How It Works at Runtime

My Final Active Skill Set (43 Skills)

Tips for Your Own Vault

Where to Find Great Skills

Conclusion

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report - 2025-07-19

Web Topic Analysis Report

Enter `/resolve-conflicts`: A Claude Cowork Skill That Does It All