Skip to content

Instantly share code, notes, and snippets.

@ajmoorexyz

ajmoorexyz/1-CLAUDE.md

Forked from themangoemoji/1-CLAUDE.md
Created March 18, 2026 20:59
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ajmoorexyz/d10743fb7a3150ba88c85a72cf912b76 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ajmoorexyz/d10743fb7a3150ba88c85a72cf912b76 to your computer and use it in GitHub Desktop.
Download ZIP
Skill-First Dispatcher Protocol for Claude Code (~/.claude)
Raw
1-CLAUDE.md

Primary Directive: Skill-First Dispatcher Protocol

Identity: You are a Skill-Centric Operator. Your primary workspace is ~/.claude/. Execute tasks through the lens of Skills, Agents, and Commands.

Phase 1: Pre-Flight Registry Lookup

Before responding to any input, consult ~/.claude/conventions/DISPATCHER_REGISTRY.yaml:

cat ~/.claude/conventions/DISPATCHER_REGISTRY.yaml

Match user intent against keywords arrays in the registry.

Phase 2: Decision Matrix

Choose exactly ONE path:

Path Condition Action
PATH A: EXECUTE Skill/command exists Announce: "Using [Name] to handle this..." then follow its .md instructions
PATH B: REFINE Skill exists but needs context Ask for the missing piece before executing
PATH C: BUILD No matching skill Say: "I don't have a skill for this yet. Should I build skills/[new-name] before we proceed?"

Phase 3: Skill-Ready Output

Every substantial output should be "Skill-Ready":

  • After generating a reusable solution, ask: "Should I save this logic into a new skill or update an existing one?"
  • After multi-step sequences complete: "Should I save this workflow as a skill?"

Constraints

  • Minimize chatty preamble
  • Maximize tool-use and directory-alignment
  • Default to PATH C (build new skill) when uncertain
Raw
2-DISPATCHER_REGISTRY.yaml
# Dispatcher Registry
# Single source of truth for skill-first routing
# Updated by: registry-sync skill
# Last sync: 2024-02-23
skills:
- name: arxiv-to-md
path: skills/arxiv-to-md
description: Convert arXiv papers to LLM-consumable markdown
keywords: [arxiv, paper, pdf, markdown, academic]
- name: cc-history
path: skills/cc-history
description: Analyze Claude Code conversation history files
keywords: [history, conversation, tokens, sessions]
- name: codebase-analysis
path: skills/codebase-analysis
description: Systematic codebase exploration and architecture review
keywords: [analyze, repo, codebase, architecture, understand]
- name: decision-critic
path: skills/decision-critic
description: Stress-test decisions and reasoning
keywords: [decision, trade-off, should, critique, evaluate]
- name: doc-feedback-review
path: skills/doc-feedback-review
description: Read external docs and discuss feedback
keywords: [document, feedback, review, discuss, comments, gdoc, google doc]
- name: deepthink
path: skills/deepthink
description: Structured reasoning for open-ended analytical questions
keywords: [think, reason, analyze, consider, ponder]
- name: doc-sync
path: skills/doc-sync
description: Synchronize documentation across a repository
keywords: [docs, sync, documentation, readme]
- name: incoherence
path: skills/incoherence
description: Detect inconsistencies between spec and implementation
keywords: [inconsistent, mismatch, spec, implementation, drift]
- name: planner
path: skills/planner
description: Interactive planning and execution for complex tasks
keywords: [plan, implement, build, steps, breakdown]
- name: problem-analysis
path: skills/problem-analysis
description: Root cause investigation and problem decomposition
keywords: [problem, root cause, investigate, why, failing]
- name: prompt-engineer
path: skills/prompt-engineer
description: Optimize and engineer prompts
keywords: [prompt, optimize, improve, engineer]
- name: refactor
path: skills/refactor
description: Technical debt review and code quality improvement
keywords: [refactor, technical debt, code quality, clean]
- name: skill-manager
path: skills/skill-manager
description: Meta-skill for creating and managing skills
keywords: [create skill, save skill, new skill, workflow]
- name: registry-sync
path: skills/registry-sync
description: Sync DISPATCHER_REGISTRY.yaml with filesystem
keywords: [registry, sync, update, index]
- name: monorepo-git
path: skills/monorepo-git
description: Git conventions for backend monorepo (sparse checkout, fast-fetch)
keywords: [git, sparse, checkout, branch, fetch, monorepo, spt]
- name: branch-workflow
path: skills/branch-workflow
description: Branch workflow with JIRA sync and quality checklist
keywords: [start work, working on, ticket, jira, checklist, review, branch]
- name: java-conventions
path: skills/java-conventions
description: Java coding patterns and ADRs (virtual threads, records, testing, DI, exception handling)
keywords: [java, virtual threads, blocking, async, apollo, grpc, pubsub, jackson, json, records, junit, assertj, guice, dagger, constructor injection, exception, error handling, try catch]
- name: logon
path: skills/logon
description: Daily planning workflow - review Jira tickets, update status, pick work
keywords: [logon, login, start day, daily, planning, tickets, jira, morning, standup]
- name: logoff
path: skills/logoff
description: End-of-day workflow - review progress, update Jira, generate snippets
keywords: [logoff, logout, end day, wrap up, snippets, evening, done, finished]
- name: cinder-new-entity-checklist
path: skills/cinder-new-entity-checklist
description: Checklist for implementing new entity types in cinder-adapter
keywords: [cinder, entity, new, checklist, cocam, routing, adapter, implementation]
agents:
- name: architect
path: agents/architect.md
description: High-level system design and structural planning
keywords: [design, architecture, system, structure]
- name: codebase-analyzer
path: agents/codebase-analyzer.md
description: Analyze HOW code works with file:line references
keywords: [trace, flow, implementation, details]
- name: codebase-locator
path: agents/codebase-locator.md
description: Find files and directories relevant to a feature
keywords: [find, locate, search, where]
- name: debugger
path: agents/debugger.md
description: Systematic bug investigation and evidence gathering
keywords: [debug, bug, error, fix, investigate]
- name: developer
path: agents/developer.md
description: Implement specifications with tests
keywords: [write, implement, code, develop]
- name: java-test-reviewer
path: agents/java-test-reviewer.md
description: Analyze Java code and review test coverage
keywords: [java, test, coverage, junit]
- name: jira-expert
path: agents/jira-expert.md
description: Retrieve, summarize, and create Jira issues
keywords: [jira, ticket, issue, story]
- name: quality-reviewer
path: agents/quality-reviewer.md
description: Review code for production risks and quality
keywords: [review, quality, risk, production]
- name: router
path: agents/router.md
description: Master routing agent for skill/agent dispatch
keywords: [route, dispatch, find, which]
- name: spotify-tool-researcher
path: agents/spotify-tool-researcher.md
description: Research Spotify internal tools and libraries
keywords: [spotify, internal, techdocs, slack]
- name: technical-writer
path: agents/technical-writer.md
description: Create documentation optimized for LLM consumption
keywords: [docs, documentation, write, readme]
commands:
- name: clarify
path: commands/clarify.md
description: Requirements clarification workflow
keywords: [clarify, requirements, unclear, ambiguous]
- name: cleanup-worktree
path: commands/cleanup-worktree.md
description: Full worktree removal and cleanup
keywords: [cleanup, worktree, remove, delete]
- name: close-worktree
path: commands/close-worktree.md
description: Close and archive a git worktree
keywords: [close, worktree, archive, finish]
- name: commit
path: commands/commit.md
description: Stage modified files and create commits
keywords: [commit, git, stage, save]
- name: worktree
path: commands/worktree.md
description: Git worktree lifecycle management
keywords: [worktree, branch, parallel, git]
- name: snippets
path: commands/snippets.md
description: Generate performance review snippets from Jira and GitHub
keywords: [snippets, performance, review, jira, github, pr, month]
Raw
3-registry-sync-skill.md
description Sync DISPATCHER_REGISTRY.yaml with filesystem state

Registry Sync

Scans ~/.claude/ subdirectories and updates ~/.claude/conventions/DISPATCHER_REGISTRY.yaml to maintain a single source of truth for the dispatcher protocol.

When to Run

  • After adding a new skill, agent, or command
  • After deleting or renaming existing tools
  • When registry appears stale or incomplete
  • Periodically to ensure accuracy

Process

1. Crawl Directories

Scan for .md files in:

~/.claude/skills/*/skill.md      # Skill definitions
~/.claude/skills/*/              # Skill directories (check for CLAUDE.md too)
~/.claude/agents/*.md            # Agent definitions
~/.claude/commands/*.md          # Command definitions

2. Extract Metadata

For each file found, extract:

  • name: Directory name (skills) or filename without extension (agents/commands)
  • path: Relative path from ~/.claude/
  • description: First line after frontmatter, or description: from frontmatter
  • keywords: Inferred from name, description, and content headings

3. Compare with Registry

Load current DISPATCHER_REGISTRY.yaml and identify:

  • New entries: Files on disk not in registry
  • Removed entries: Registry entries without corresponding files
  • Stale entries: Description or path mismatches

4. Update Registry

Write updated YAML with:

  • Timestamp in header comment
  • Sorted entries within each section
  • Preserved keywords (can be manually curated)

5. Report Changes

Output summary:

Registry Sync Complete
----------------------
Added:   skills/new-skill, commands/new-command
Removed: agents/deprecated-agent
Updated: skills/existing-skill (description changed)

Manual Keyword Curation

Keywords are initially auto-generated but can be manually refined. The sync preserves existing keywords for entries that haven't changed paths.

Output

Updated ~/.claude/conventions/DISPATCHER_REGISTRY.yaml

Usage

Invoke when registry needs refresh:

"Sync the registry" "Update DISPATCHER_REGISTRY" "Index my skills"

Raw
4-skill-manager-skill.md
description Meta-skill for creating, registering, and managing skills

Skill Manager

The "Skill Factory" - creates new skills when manual tasks are repeated.

Trigger Conditions

Invoke this skill when:

  1. You find yourself doing a manual task twice
  2. User requests "save this as a skill"
  3. Router agent identifies a workflow worth persisting
  4. A multi-step sequence completes successfully and could be reused

Process

1. Analyze the Workflow

Identify the repeatable pattern:

  • What was the trigger/intent?
  • What steps were executed?
  • What context was required?
  • What was the output format?

2. Determine Skill Type

Type Location Use Case
Command ~/.claude/commands/*.md User-invocable, simple workflows
Skill (simple) ~/.claude/skills/<name>/skill.md Declarative, markdown-based
Skill (scripted) ~/.claude/skills/<name>/*.py Complex, multi-step, stateful
Agent ~/.claude/agents/*.md Specialized subagent behavior

3. Create the Skill

For Commands (user-invocable, simple):

---
description: <one-line description>
argument-hint: "[optional args]"
---

# <Command Name>

## Pre-requisites
- Check `skills/<relevant-skill>` for dependencies
- Check `conventions/<relevant>.md` for formatting

## Process
1. Step one
2. Step two
...

## Usage
- `/<command>` - Basic usage
- `/<command> "arg"` - With arguments

For Skills (declarative):

Create ~/.claude/skills/<name>/skill.md:

---
description: <description for skill invocation>
---

# <Skill Name>

## Purpose
<what this skill accomplishes>

## Steps
1. ...
2. ...

## Output
<expected output format>

For Scripted Skills:

Follow patterns in ~/.claude/skills/README.md:

  1. Create directory: ~/.claude/skills/<skill-name>/
  2. Create Python module in ~/.claude/skills/scripts/skills/<skill_name>/
  3. Follow section ordering from README
  4. Register in skill CLAUDE.md

4. Register in CLAUDE.md

Update ~/.claude/skills/CLAUDE.md to add the new skill to the subdirectory table.

5. Confirm Creation

Report to user:

  • Skill name and location
  • How to invoke it
  • Any refinements needed

Context Headers

When creating commands, include context headers for self-awareness:

## Pre-requisites
- Check `skills/code-quality` for linting rules
- Check `conventions/intent-markers.md` for formatting
- Review `cc-history` for recent related changes

Anti-patterns

  • Don't create skills for one-time tasks
  • Don't duplicate existing skill functionality
  • Don't create overly narrow skills (combine related workflows)
  • Don't skip registration in CLAUDE.md

Usage

Invoke explicitly:

"Save this workflow as a skill"

Or automatically triggered by Router agent after successful multi-step completion.

Raw
5-router-agent.md

Router Agent

Master routing agent that orchestrates specialized agents and skills.

Purpose

Sits in front of all specialized agents, scanning available skills and agents to determine the best execution path for any user request.

Routing Process

1. Discovery Phase

Scan available resources:

~/.claude/skills/     # Script-based workflows
~/.claude/commands/   # User-invocable commands
~/.claude/agents/     # Specialized agents

2. Intent Matching

Match user request against:

Resource Type Keywords/Patterns Example Match
codebase-analysis "analyze repo", "understand codebase", "architecture" "Analyze this repo"
refactor "refactor", "technical debt", "code quality" "Review code quality"
problem-analysis "root cause", "investigate", "why" "Why is this failing?"
decision-critic "should I", "trade-offs", "stress-test" "Should I use Redis?"
deepthink "think through", "reason about" "Think through this design"
planner "plan", "implement", "build" "Plan this feature"
developer "write", "implement", "code" "Write a function"
debugger "debug", "fix", "error" "Debug this error"
architect "design", "architecture", "system" "Design the system"

3. Execution Handoff

Once matched, hand off with full context:

Matched: {skill_name}
User Intent: {original_request}
Context: {relevant_files, history, constraints}

4. Completion Loop

After task completion, ask:

"Task complete. Should I save this sequence as a new skill?"

If yes, invoke skill-manager to persist the workflow.

Fallback Behavior

If no match found:

  1. Ask user to clarify intent
  2. Suggest closest matching skills
  3. Offer to create a new skill for this task type

Agent Registry

Skills (Script-Based Workflows)

  • codebase-analysis - Repository architecture exploration
  • refactor - Technical debt and code quality
  • problem-analysis - Root cause investigation
  • decision-critic - Decision stress-testing
  • deepthink - Structured reasoning
  • planner - Implementation planning
  • prompt-engineer - Prompt optimization
  • incoherence - Spec/implementation consistency
  • doc-sync - Documentation synchronization
  • arxiv-to-md - Paper conversion
  • cc-history - Conversation history analysis
  • skill-manager - Meta-skill for creating new skills

Agents (Specialized Subagents)

  • developer - Code implementation
  • debugger - Bug investigation
  • architect - System design
  • quality-reviewer - Code review
  • codebase-locator - File discovery
  • codebase-analyzer - Implementation analysis
  • technical-writer - Documentation
  • java-test-reviewer - Test coverage analysis

Commands (User-Invocable)

  • commit - Git commit workflow
  • clarify - Requirements clarification
  • worktree - Git worktree management
  • close-worktree - Worktree cleanup
  • cleanup-worktree - Full worktree removal

Usage

This agent should be invoked implicitly by the Primary Directive when no direct skill match is obvious, or explicitly when the user wants help finding the right tool for a task.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment