
shark-skills
Running Claude Code like an engineering team: one operator, parallel lanes, audited merges.
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up shark-skills (claude-plugin project) into my current project. Found on https://claudeers.com/shark-skills Repo: https://github.com/tusharsrivastava/shark-skills Homepage/docs: — Detected install method: claude-plugin → /plugin install shark-skills@tusharsrivastava/shark-skills Category: devtools. Platforms: api, mobile. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: unknown; community-verified: false. Confirm the source before running anything.
⚠ Unverified / not recently updated — review before pasting a run-this config.
/plugin marketplace add tusharsrivastava/shark-skills /plugin install shark-skills@tusharsrivastava/shark-skills
git clone https://github.com/tusharsrivastava/shark-skills
// compatibility
| Platforms | api, mobile |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | JavaScript |
Running Claude Code like an engineering team: one operator, parallel lanes, audited merges.
Install • Why shark • Reference • Contributing
My Claude Code setup for building real features with a team of agents.
Using a single Claude Code session for a small fix works fine. Using it for a real feature usually turns into a mess of conflicting edits, silently dropped rules during merges, half-baked bug patches, and a giant commit at the end.
Throwing more agents at it doesn't fix that on its own. Parallel agents with no shared plan just make code messier, faster.
shark is what I ended up with after building a production system this way.
The main session never writes code. It becomes the operator: it briefs the subagents, checks what they hand back, and talks to you. Lanes build in parallel against one shared contract. Every merge gets audited, and every bug gets a root cause before it gets a fix.
Every rule in here exists because breaking it cost me hours. Steal them. Change them. Make them stricter for your project.
See It in Action
A real session, recorded with asciinema.
Installation (2-minute setup)
1. Get the plugin
In Claude Code:
/plugin marketplace add tusharsrivastava/shark-skills
/plugin install shark@shark-skills
You'll also need git, and Node.js with npx. The debugger MCP server runs through it.
Try it without installing
git clone https://github.com/tusharsrivastava/shark-skills
claude --plugin-dir ./shark-skills
Turn it on for your whole team
Add this to .claude/settings.json in your repo. Everyone who opens the repo gets the plugin.
{
"extraKnownMarketplaces": {
"shark-skills": { "source": { "source": "github", "repo": "tusharsrivastava/shark-skills" } }
},
"enabledPlugins": { "shark@shark-skills": true },
"outputStyle": "shark:asd-ste100"
}
To update, run /plugin marketplace update shark-skills and start a new session.
2. Run /shark:init
You only need to configure it once per project. In your repo, run:
/shark:init
It will:
- Find your
AGENTS.mdorCLAUDE.md, or create anAGENTS.mdif you have neither - Add the sections shark needs (commands, invariants, architecture rules, test scope, secrets, docs layout, owner rules and session harness) and the working rules, without touching what you already have
- Notice if you already run your own orchestrator, and ask which one leads, so your file never gets two start rules
- Ask for each value it can't find, with a suggested value for each
- Set the project's output style to
shark:asd-ste100in.claude/settings.json, so replies are short, outcome-first and end with a summary and action items
The skills never hardcode a command. They run a key from your Commands table, so the same kit works on Python,
JS/TS, Go, or anything with a test command.
Example
| Key | Command | Limit or note |
| --- | --- | --- |
| `gate:fast` | `pnpm lint && pnpm tsc --noEmit && vitest run` | At most 5 min. |
| `test <paths>` | `vitest run <paths>` | |
When a skill says "run gate:fast", this is the line it runs.
[!TIP] After
/shark:init, your project file tells Claude to load/shark:operatorat the start of each session. You don't need to type it every time, and your session becomes a full-fledged engineering team. Already use your own orchestration loop? Keep it in charge, and shark stays on call.
Prefer to set it up by hand?
Copy AGENTS.md to your repo root and fill in the sections at the top. Already have a CLAUDE.md?
Merge the sections into it. Claude Code only reads AGENTS.md when there's no CLAUDE.md, or when the
claude-md-and-agents-md setting is on.
3. That's it. You're running a team now.
Why shark Exists
Before building shark, I built baseline, but it became too bulky for newer and improved coding models. shark skills are lean, and they scale in parallel without impacting the code quality I yearn for.
shark turns your harness into a lean, mean coding machine.
#1: The Agents Stepped On Each Other
"Adding manpower to a late software project makes it later."
Fred Brooks, The Mythical Man-Month
The Problem: You run three agents in parallel. It looks three times faster. Then you merge. Two agents changed the name of the same function. A third agent made its own version of an event. The merge takes a third of your afternoon.
The Fix: Write a contract before you split the work. One agent writes the round contract in 5 to 10 minutes. The contract gives each shared name one owner file. It lists each writer and each reader of each event. It sets the boundaries of each lane. Each lane reads the contract first. When a lane finds a shared item, it stops and reports. It does not decide alone.
/shark:operatordoes the contract step and writes the briefs.shark:code-writerbuilds one lane in its own worktree. It writes the test first.shark:lead-engineermerges the lanes. It checks each lane against the contract.
#2: A Refactor Missed Some Business Rules
"If you don't see the use of it, I certainly won't let you clear it away."
G.K. Chesterton, The Thing
The Problem: Rules hide in small places: a guard clause, a branch in a helper, a check from an old incident. A rewrite or a merge removes one of them. All the tests still pass. You find the problem in production.
The Fix: Write your invariants one time. Then check each diff against them. Do not remove a rule until you know why it is there.
shark:invariant-guardcompares a diff with your## Invariants. It reports each break withfile:lineevidence. It is read-only, so it cannot change your code./shark:merge-auditchecks each merge against the patch notes. A different agent does the audit, not the agent that did the merge./shark:port-auditfinds the rules that a rewrite removed./shark:patch-fanoutputs them back, in parallel.
Example invariants
- Tenant isolation. Each query on tenant data runs inside a tenant context.
- Money. Money is an integer of minor units with a currency. Never a float.
- Idempotency. A retried request with the same key gives the same result. It makes one change only.
- One unit of work. A write, its event and its job commit in one transaction.
#3: Production Is On Fire And You're On The Call
"Quit thinking and look."
David J. Agans, Debugging: The 9 Indispensable Rules
The Problem: You ask an agent to fix a bug. The agent reads the code and makes a guess. It changes the code at the symptom. Two days later, the bug occurs again with a new stack trace.
The Fix: Find the cause first. Fix it second. Two different agents do these two tasks.
shark:code-debugger runs your program in a real step-through debugger (Python,
JS/TS, Go, Rust, Java, .NET, C/C++). It records the real values. It gives you three items: the root cause, a
failing regression test, and a fix spec. Then shark:code-writer changes the production code.
A bug report with one symptom takes the direct path: a failing test first, then the fix. A report with two or more
symptoms, or a defect in twin code paths, gets more. The operator writes the properties that the report breaks,
plus four default properties (scope isolation, guard preservation, twin equivalence, input forms). It splits them
into zones, and one shark:code-debugger investigates each zone in parallel, in its own copy of the repository. A
merge debugger combines the zones and closes the spec with /shark:solution-spec:
each behaviour decision is a row with a test. Then a Sonnet shark:code-writer builds it. Scripts check each step:
rca-gate.mjs refuses an RCA with an open cell or an open spec.
A report with more than one symptom gets more. The operator writes the properties that the report breaks, and four
default properties (scope isolation, guard preservation, twin equivalence, input forms). It splits them into zones,
and one shark:code-debugger investigates each zone in parallel, in its own copy of the repository. A merge
debugger combines the zones and closes the spec with /shark:solution-spec:
each behaviour decision is a row with a test. Then a Sonnet shark:code-writer builds it. Scripts check each
step: rca-gate.mjs refuses an RCA with an open cell or an open spec.
/shark:debug-rca contains the method. You can also use it yourself.
#4: One Giant Commit At The End
"Make the change easy (warning: this may be hard), then make the easy change."
Kent Beck
The Problem: An agent works for a long time. It changes the structure of the code and adds three behaviours.
All of it goes into one commit of 4,000 lines. Nobody can review it. You cannot revert one part of it. git bisect
cannot find the bad change.
The Fix: Change the structure first, in its own commit. Then change the behaviour, in a different commit.
/shark:commit-blocks splits the working tree into conventional commits. Each
commit has one reason. A refactor and a behaviour change never share a commit. A script checks that each commit
passes the gate. Thus git bisect works on your history.
#5: Hours Spent Finding One Blocker At A Time
"How does a project get to be a year late? ... One day at a time."
Fred Brooks, The Mythical Man-Month
The Problem: The agent runs the slow end-to-end flow. It finds one failure and fixes it. Then it runs the flow again and finds the next failure. Each cycle takes 20 minutes. The estimate grows by hours, and nobody sees it.
The Fix: Find all the known defects first, with one static scan. Then fix them in rounds.
/shark:goal-loopsorts the failing scenarios and writes the contract. It fixes them in lanes, merges one time, and runs the flow again.- Each agent has a timebox: 20 minutes for a lane. It gets one grace period of 20% to complete its current step.
- The costly checks run last, one time each:
gate:full, integration tests and benchmarks.
[!TIP] The
Working rulessection ofAGENTS.mdlists all the rules. Each rule names the failure that it prevents. An example:pytestwith a folder and a file in that folder collects only the file.
Summary
AI made writing code cheap, but the engineering is still expensive. With shark, you can build production-grade systems with confidence: systems that are well written, well documented, and easy to debug when production is on fire. That's not vibe coding. That's real engineering. It is my decade of experience building and maintaining production-scale systems, distilled into this setup.
Reference
Session
- /shark:init: Set up a project once. Brings your
AGENTS.mdorCLAUDE.mdin line with the shark template, so every session starts with the operator, or with your own orchestrator if you keep it. Sets theshark:asd-ste100output style for the project. - /shark:operator: Run the session. Sets the mode, writes the briefs, routes the
work to agents, and checks what comes back. Loads by itself after
/shark:init. - /shark:handoff: Record and prune the handoff file, so the next session picks up where this one stopped.
Build and merge
Skills
- /shark:goal-loop: Fix rounds toward one goal across N failing scenarios: classify, contract, fix in lanes, merge, run again.
- /shark:patch-fanout: Port many independent patches in parallel, one agent and one branch each.
- /shark:lead-merge: Merge patch branches in batches from a queue file.
- /shark:merge-audit: Review each merge against the patch notes and your invariants.
- /shark:port-audit: Find the rules a rewrite lost, by auditing the commits that deleted them.
- /shark:commit-blocks: Split a working tree into conventional commits that each pass the gate.
- /shark:code-authoring: The writing rules of
code-writerandlead-engineer: regression safety with a test baseline, scope, test first, logging, comments. - /shark:solution-spec: Close a spec before a Sonnet writer builds it: the guards on the path, a behaviour table with a test for each row, the decisions, an adversarial check.
- /shark:code-authoring: The writing rules of
code-writerandlead-engineer: regression safety with a test baseline, scope, test first, logging, comments. - /shark:solution-spec: Close a spec before a Sonnet writer builds it: the guards on the path, a behaviour table with a test for each row, the decisions, an adversarial check.
Agents
- shark:code-writer: Turn a spec or a fix spec into production code, test first.
- shark:lead-engineer: Merge parallel lanes, check them against the round
contract, and run
gate:fast.
Debug and design
Skills
- /shark:debug-rca: Step through the running program and write a root-cause analysis from observed values.
- /shark:system-design: Check a design: SOLID, typed state, one rule in one place, pinned contracts, evaluation first.
Agents
- shark:code-debugger: Find the root cause in the debugger, then write a failing regression test and a fix spec.
- shark:invariant-guard: Audit a diff against your invariants, read-only, with
file:lineevidence. - shark:architect: Senior read-only review of the architecture, the code and its math. Costly, so save it for big designs.
Docs and upkeep
Skills
- /shark:cookbook-writing: The method and reading-level script for tutorial chapters.
- /shark:gitignore: Create or refresh
.gitignorefrom gitignore.io without losing your own rules.
Agents
- shark:doc-writer: Write specs, design notes, findings reports and runbooks.
- shark:cookbook-writer: Write tutorial chapters and check their reading level.
Also in the box
- deny-secrets hook: Refuses Read, Edit, Write, Grep and Bash calls on the secret
files that your
## Secretssection lists (.env,*.pemand similar by default). Example files (.env.exampleand similar) always stay readable, so agents still learn the setting names. - mcp-debugger: The MCP server behind
shark:code-debugger. Real breakpoints, stepping and variable reads for Python, JS/TS, Go, Rust, Java, .NET and C/C++. It writes its log to.claude/mcp-debugger.log, so add that to your.gitignore. - shark:asd-ste100: An output style in Simplified Technical English. Short sentences, outcome first, observed and inferred claims labelled. Your agents' reports stop rambling.
- AGENTS.md: The project template, with the working rules.
/shark:initapplies it for you.
Contributing
Issues and pull requests are welcome. Read CONTRIBUTING.md first. The short version: no project
values, no stack lock-in, and commands named by their AGENTS.md key. Test your change with
claude --plugin-dir <kit folder> in a project that has a filled AGENTS.md.
Found a security problem? Follow SECURITY.md, and don't open a public issue.
License
MIT. The AGENTS.md template and the logo in assets/ are
CC0, so you can copy them with no notice at all.
ASD-STE100 and Simplified Technical English are trademarks of ASD, Brussels. shark isn't affiliated with ASD. The
debugger is @debugmcp/mcp-debugger (MIT). It runs through npx and
isn't bundled.
// faq
What is shark-skills?
Running Claude Code like an engineering team: one operator, parallel lanes, audited merges.. It is open-source on GitHub.
Is shark-skills free to use?
shark-skills is open-source under the MIT license, so it is free to use.
What category does shark-skills belong to?
shark-skills is listed under devtools in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/shark-skills)
// retro hit counter
[](https://claudeers.com/shark-skills)
// reviews
// guestbook
// related in Developer Tools
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…
Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.
AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…
Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA