claude-dev-skill

What is claude-dev-skill?

claude-dev-skill is a custom skill for Claude Code that turns Claude into a “tech lead” process for building software with multiple AI worker agents. The skill provides a structured multi-phase workflow that coordinates parallel worker work in isolated worktrees, aiming to reduce lost context and merge conflicts by routing changes through PRs and review.

Its core purpose is to move beyond single-threaded code generation: it guides requirements alignment (PRD), architecture decisions, task decomposition, parallel implementation, static QA checks, and a structured PR review/merge step.

Key Features

• /dev command workflow (multi-phase SOP): Starts with request classification and runs through PRD alignment, architecture and issue creation, worker implementation, QA verification, and PR merge coordination.
• Tech-lead routing rule: The main conversation is treated as a coordinator; it “never writes code directly,” requiring changes to go through a Worker Agent → PR → review process.
• Parallel Worker Agents via worktrees: Spawns multiple worker agents that develop in parallel in isolated worktrees to support different parts of the feature (e.g., auth, API, frontend).
• Pre-coding conflict scan: Before work starts, worker agents scan other open Issues for file overlap to catch likely conflicts earlier.
• Post-merge PR coordination: After merges, it scans open PRs and notifies branches that need rebase.
• Security gate before review: Enforces running security tools (e.g., bandit plus pip-audit for Python, or npm audit for Node) as a required step before the review phase.
• Structured PR review checklist with veto conditions: Code review is done through a 7-item checklist with mandatory veto conditions.
• Counterexample self-check for test coverage: Includes a six-category self-check intended to ensure workers consider Null/Empty/Boundary/External failure/Concurrency/Malicious input scenarios.

How to Use claude-dev-skill

1. Install the skill files into Claude Code’s commands directory (script-based install for macOS/Linux/Windows, or manual copy while preserving the directory structure).
2. Ensure you have Claude Code (Anthropic official CLI) logged in.
3. Use the GitHub CLI (gh) with an authenticated session (run gh auth login first).
4. In Claude Code, run /dev [optional description]. The skill will classify the request (e.g., new project, new feature, bug fix, hotfix, architectural change, refactoring) and enter the appropriate flow.

A typical run follows the phases shown in the repository: PRD alignment (two rounds), architecture and task decomposition with GitHub Issues, worker execution in parallel worktrees, QA static verification, and a checklist-driven PR review and merge.

Use Cases

• Building a small-to-medium web backend feature with an existing PRD: Use /dev to translate an existing product requirement document into architecture decisions, GitHub Issues, and parallel worker implementations.
• Implementing multiple modules at once while minimizing merge conflicts: Have separate worker agents handle different components (e.g., authentication vs. task CRUD API vs. frontend components) and rely on pre-coding conflict scanning and post-merge rebase coordination.
• Coordinated bug fixing or hotfix work: For bug fixes or emergency hotfixes, the flow classifies the request type and routes it through architecture review, worker changes, QA verification, and structured PR merge.
• Systematic refactoring with structured review: When refactoring, the SOP’s counterexample self-check and pre-merge security gate help ensure workers consider edge cases and run required audit tooling before review.
• Architecture change work that requires alignment before coding: Use Phase 1 PRD alignment and Phase 2 architecture decisions to ensure the team’s plan is clarified before workers start implementation.

FAQ

• What does “tech lead” mean in this skill’s workflow? The main conversation acts as a coordinator: it aligns on PRD, decides architecture direction, spawns worker agents, and enforces that code changes flow through Worker Agent PRs and review rather than direct edits in chat.

• Does claude-dev-skill write code directly from the main conversation? No. The workflow includes an “iron rule” that the main conversation never writes code directly; changes are expected to go through a Worker Agent and then a PR for review.

• How are conflicts handled during parallel development? The skill includes a pre-coding conflict scan (worker agents check open Issues for file overlap before starting) and a post-merge step that scans open PRs to identify branches that need rebase.

• What security checks are enforced? Before the review phase, it mandates running security tooling such as bandit plus pip-audit for Python, or npm audit for Node, per the repository’s Security gate description.

• Is this intended for production deployment work? The repository’s scope notes it is not suited for projects requiring production deployment because it does not provide DevOps/deployment capability.

Alternatives

• Single-agent code assistants (autocomplete/chat-style): These focus on writing code directly from prompts, but typically don’t provide a multi-agent, PRD-to-PR workflow with enforced review gates.
• Conventional multi-step prompting + manual PR workflows: You can prompt Claude yourself to decompose tasks and then run workers manually, but you lose the built-in SOP structure (classification, conflict scanning, QA and checklist review coordination).
• Standard GitHub-driven team workflows (Issues/PRs without AI SOP): Teams can replicate parts of the flow using GitHub Issues and PR reviews, but the “worker agent” parallelization and automated phase routing are not provided in the same way.
• Other Claude Code custom skills focused on planning or testing: Instead of coordinating parallel worker agents end-to-end, some skills may target only one part of the workflow (e.g., test generation), leaving integration and merge coordination to the user.