Skippy is a layered engineering system for coding agents: playbooks, decision
rules, verification gates, and portable project skills. Each
projects/<slug>/SKILL.md captures live repository conventions, validation,
review handling, and submission practices for one upstream project.
You describe the outcome; Skippy runs the method: reproduce the problem, pick the owning boundary, verify at a real edge, and keep open PRs merge-ready without re-explaining the repo every session. You get accountable delivery you can trust or hand off: visible plans, signed commits, addressed review threads, and proof the change works, not a patch that only looked right in chat.
It is not patching alone. Skippy covers investigation, bug fixes, features, refactors, performance work, security hardening, PR maintenance, repository bootstrap, and long autonomous runs on public OSS, private repos, or internal monorepos.
Coding agents generate plausible patches quickly. They are much weaker at the engineering around them: reproducing the failure, choosing the smallest owning boundary, knowing when a green build is not proof, learning from review, and handing off work another engineer can trust without redoing it.
Skippy closes that gap. You describe the outcome; Skippy routes the request to a playbook, loads the project skill for that repository, builds a visible task plan, coordinates bounded specialist work when it helps, and refuses to report success until the changed behavior is verified at a real boundary.
It is not a prompt pack or a skill library on its own. It is a layered engineering system of decision rules, playbooks, project adapters, task artifacts, role boundaries, helper programs, and a verification gate that turns agent work into accountable delivery.
%%{init: {'theme':'neutral'}}%%
flowchart LR
A["Outcome and constraints"] --> B["Skippy router"]
B --> C["Project skill"]
B --> D["Decision system"]
B --> E["Playbook"]
C --> F["Task plan"]
D --> F
E --> F
F --> G["Bounded implementation"]
G --> H["Real-boundary verification"]
H --> I["Review and delivery receipt"]
The standard is simple: write less code, own the right boundary, and prove what changed.
Skippy follows how a strong engineer joins a codebase: read docs and history, understand open and closed merge requests, contribute, learn from outcomes, and keep improving. That learning is evidence-backed: bootstrap a new repository from its sources, ship real changes, then run a calibrated continuous learning loop instead of rewriting instructions from noise.
The method is in production across major open-source projects (tables below). The same mechanism applies to private repos and internal monorepos; public OSS is where the review history is easiest to bootstrap against.
These contributions were assisted by Skippy.
| Project | Contributions | Open | Merged | Merged % |
|---|---|---|---|---|
 Apache Airflow |
31 | 5 | 9 | 29.0% |
 Apache Hadoop |
15 | 8 | 4 | 26.7% |
 Apache Spark |
4 | 2 | 0 | 0.0% |
 Apache Superset |
2 | 2 | 0 | 0.0% |
 ClawHub |
21 | 0 | 9 | 42.9% |
 Hermes Agent |
11 | 9 | 0 | 0.0% |
 Inspect AI |
32 | 4 | 14 | 43.8% |
 Inspect Petri |
3 | 0 | 1 | 33.3% |
 Megatron-LM |
5 | 5 | 0 | 0.0% |
 OpenClaw |
30 | 1 | 4 | 13.3% |
 OpenShell |
1 | 0 | 0 | 0.0% |
 PyTorch |
23 | 12 | 6 | 26.1% |
| SkillSpector |
9 | 5 | 4 | 44.4% |
 Slurm |
3 | 3 | 0 | 0.0% |
 ts-mono |
8 | 2 | 6 | 75.0% |
| Total Contributions | 198 | 58 | 57 | 28.8% |
Total Contributions: 198 · Success Rate: 28.8% merged (57 of 198)
These contributions were not assisted by Skippy.
| Project | Contributions | Open | Merged | Merged % |
|---|---|---|---|---|
 Apache Avro |
1 | 1 | 0 | 0.0% |
 Apache Druid |
1 | 0 | 1 | 100.0% |
 nvidiagpubeat |
Creator and maintainer | N/A | N/A | N/A |
 Apache Pig |
2 | 0 | 2 | 100.0% |
 Apache Zeppelin |
6 | 0 | 0 | 0.0% |
 Scoobi |
2 | 0 | 0 | 0.0% |
| Total Contributions | 12 | 1 | 3 | 25.0% |
Refresh counts with projects/oss-contribution-readme/SKILL.md.
Skippy applies to any non-trivial engineering work on any repository you can read (public Git, private Git, internal monorepos). The playbooks cover investigation, bug fixes, features, refactors, performance, security, and long autonomous runs, not only external contribution.
| Entry | When to use it |
|---|---|
| Focused task | You know the outcome: fix a bug, add behavior, investigate a system. |
| Onboard to a repository | Skippy does not know this codebase yet, or you want to maintain a queue of in-flight changes and keep learning. |
The project skills table lists repositories that already have adapters. Many are public OSS projects because their code and review history are easy to bootstrap against; your own repositories use the same mechanism.
When you already know the issue, task, or outcome, give Skippy the concrete request and preserved behavior:
skippy The OAuth callback occasionally creates duplicate sessions.
Reproduce both deliveries, trace the owning race, fix it, and prove one session
is created. Keep valid login and logout behavior unchanged.
Skippy matches the request to a playbook, loads the project skill when one exists, builds a task plan, and holds the work to the completion gate.
Use this path when a new engineer would: clone, read, learn from merge-request history, contribute, and maintain ongoing work.
%%{init: {'theme':'neutral'}}%%
flowchart LR
A["1. Bootstrap"] --> B["2. Contribute or sweep"]
B --> C["3. Learn and schedule"]
Point Skippy at a canonical repository URL it does not yet know:
skippy bootstrap https://github.com/owner/repository
Bootstrap builds a project profile through scaffold plus evidence: the agent reads architecture, design and coding rules, tools, policy, CI, and representative open, merged, and closed merge requests, then writes a project skill backed by sources. It does not modify the upstream repository. The first real task still verifies commands and environment limits.
For example:
skippy bootstrap https://github.com/meridianlabs-ai/ts-mono
For an already-supported project, skip this step. See the bootstrap playbook for the detailed output.
When you want to maintain in-flight changes and fill open slots, use this packaging of the contribution-queue playbook:
skippy sweep and replenish
Skippy maintains existing pull requests or merge requests, runs a bounded learning scan, and picks screened, non-overlapping follow-on work when policy allows. It uses the configured queue target, or 5 healthy open changes when no target is recorded, unless repository policy sets a lower maximum.
For every configured project at once, use:
skippy sweep all
Skippy launches one independent local subagent per project in parallel. Each project agent owns the complete cycle: maintain every open PR through rebases, review feedback, validation, and CI; learn from current outcomes and improve the project guidance when evidence warrants it; then replenish eligible queue slots. The main agent coordinates isolated project boundaries, recovers stopped agents, verifies each receipt, and produces one combined summary after every project finishes.
Ask your coding agent to schedule it:
Schedule a recurring task that runs:
skippy sweep and replenish
If you do not state an interval, Skippy schedules it every 30 minutes. To choose another cadence, say so explicitly:
Schedule a recurring task every hour that runs:
skippy sweep and replenish
On an agent without native recurring tasks, run skippy sweep and replenish
manually. The optional
sweep-and-replenish prompt
and continuation pack explain the full
task contract when you need to inspect or customize it.
The scheduler continues the same maintenance and replenishment method. It does not bypass project limits, quality gates, or the authority required to publish a change.
Skippy is a set of agent instructions, not a shell command. Add or attach
Skippy Mode to your coding agent, then attach the relevant
project skill under projects/. The prompts above are messages you send to the
agent, not commands to paste into Terminal unless a helper script is named
explicitly.
| Layer | Purpose |
|---|---|
| Skippy Mode | Routes the request, keeps the plan visible, selects supporting capabilities, and enforces the completion gate |
| Engineering decision system | Guides ownership, complexity, reliability, security, evidence, and delivery decisions without reducing engineering to a count of slogans |
| Playbook library | Supplies the ordered work moves for investigation, change, assurance, autonomous work, and contribution queues |
| Project skills | Supply each repository's policy, commands, layout, CI, review, and local conventions |
| Parallel-work protocol | Defines accountable integration, isolated writers, independent review, and evidence handoffs |
| Task artifacts and helpers | Make decisions, completion criteria, and verification replayable across agents and sessions |
| Contribution tracker | Verified cross-project PR counts and merge rates |
The system is intentionally layered. A project skill does not have to recreate general engineering judgment, and Skippy does not claim to know local facts it has not read from the project.
The decision system is grounded in a short, explicit engineering foundations reading map, then translated into work moves rather than copied as book summaries.
skippy/
├── skippy/ Router and specialist role definitions
├── references/ Shared contribution protocol, principles, and evidence rules
├── playbooks/ Work sequences selected by uncertainty and risk
├── projects/ One project-specific skill per repository
├── scripts/ Task-plan, decision-log, and structural-validation helpers
├── automations/ Optional continuation prompts for supported clients
└── README.md Start here (includes contribution matrix)
The top-level folders are intentional: shared engineering guidance is separate from project adapters, and reusable playbooks are separate from both.
These are the decision areas every non-trivial task can draw from. Skippy names only the principles that change a real choice in the task plan. There are 32 actionable principles across the five areas below. The five areas organize the principles; they do not replace them.
| Area | Principles used when needed |
|---|---|
| Frame the problem | explicit contracts; evidence ladder; caller and user context; facts versus inference; uncertainty; observable finish lines |
| Design the right change | owning boundary; singular authority; complexity reduction; understandable interfaces; compatibility; idempotence; failure design; reversible units |
| Build for operation | lifecycle ownership; testable security properties; real integration contracts; built-in quality; useful observability; performance budgets |
| Verify and learn | reproduction; changed-boundary proof; valid and rejection paths; diff review; replayable receipts; durable lessons |
| Collaborate without losing ownership | one integrator; stable partitions; isolated writers; bounded cognitive load; skeptical independence; complete delivery state |
Read the complete, actionable wording in the engineering decision system.
Skippy turns a requested outcome into evidence-backed delivery on any repository. Shared engineering practice joins project-specific skills; it does not apply one generic prompt everywhere.
%%{init: {'theme':'neutral'}}%%
flowchart TD
A["Issue or requested outcome"] --> B["Skippy: select work mode"]
B --> C["Project skill: live policy and commands"]
B --> D["Decision system: ownership and risk"]
B --> E["Playbook: ordered moves"]
C --> F["Task plan: evidence and done means"]
D --> F
E --> F
F --> G["Implement at owning boundary"]
G --> H["Focused plus real-boundary proof"]
H --> I["Review, CI, merge request, receipt"]
I --> J["Learning log and optional tracker"]
In practice:
- Skippy turns the request into a checkable finish condition, constraints, and a playbook.
- The project skill supplies current repo facts: policy, overlap checks where relevant, file layout, test commands, signing or review rules, and live CI expectations.
- The decision system changes the actual engineering choices: where to fix the behavior, what must remain compatible, which boundary needs realistic proof, and how to make failure and security properties explicit.
- The playbook makes the work sequence visible. It prevents an agent from dropping reproduction, validation, or review just because a patch looks plausible.
- Delivery ends with an evidence receipt. For external contribution portfolios, the OSS contribution system and contribution tracker record portfolio state without replacing the source repository's authoritative merge request.
After meaningful outcomes such as your reviews, CI results, merged or closed merge requests, and peer work on the same codebase, run the continuous learning scan. Skippy adopts only durable, source-linked rules (policy, recurring patterns, verified repairs) into the project skill or learning log. It does not rewrite its instructions from noise, single failures, or unexplained closures. That keeps the system improving the way a team culture improves: calibrated, reviewable, and tied to real evidence.
Skippy can use several agents, but only where parallel work is genuinely independent. It does not treat “more agents” as a quality guarantee.
%%{init: {'theme':'neutral'}}%%
flowchart LR
L["Lead: contract, risk, and merge owner"] --> I["Investigator: facts"]
L --> A["Architect: bounded alternatives"]
L --> W["Writer: isolated worktree"]
W --> V["Verifier: actual boundary"]
I --> M["Lead checks evidence"]
A --> M
V --> M
M --> R["Single reviewed integration"]
Before fan-out, the lead gives every delegate one bounded question or write scope, an isolated worktree or output path, expected deliverable, and stop condition. Investigators and reviewers return evidence. Only the integrator owns the final diff and delivery claim. This creates enough verification for parallel work to improve confidence without turning the repository into a shared mutable scratchpad.
When client support allows model selection, use the strongest available reasoning model for cross-cutting design and skeptical review, and a precise implementation model for a scoped edit. The proof still comes from the contract, tests, real-boundary execution, and final review, not from a model label.
Use the helper programs when a task spans multiple turns, agents, or days.
./scripts/new-task-plan.sh oauth-session-race 'Stop duplicate OAuth sessions' 'bug fix'
./scripts/check-task-plan.sh .skippy/tasks/oauth-session-race.md
./scripts/decision-log.sh .skippy/decisions/oauth-session-race.tsv reproduce \
'Two callback deliveries create two records' reproduced
./scripts/verify-skill-layout.shThe task plan holds the outcome, constraints, completion condition, selected playbook moves, and evidence. The decision log makes autonomous work reviewable instead of mysterious.
These are existing project adapters containing repository-specific facts Skippy has
already bootstrapped or scaffolded. New repositories begin with bootstrap in
Onboard to a repository. Public OSS entries below
are examples with visible history; private and internal repositories use the
same layout under projects/<slug>/.
Skippy uses portable SKILL.md files and Markdown artifacts. It can guide
Codex, Claude Code, Cursor, Gemini CLI, Aider, Continue, OpenCode, Cline, and
other agents that load local instructions.
Clients differ in their scheduler, worktree, browser, and delegation support. Skippy uses those capabilities when present and falls back to a portable core: explicit contracts, bounded work, durable artifacts, and evidence.
Skippy cannot make a model correct by declaration. It cannot bypass repository permissions, replace maintainer or reviewer judgment, or turn missing test infrastructure into a green result. Bootstrap and learning stay evidence-backed and refreshable. It exposes those limits and creates the smallest durable verification capability when the project needs one.
git clone https://github.com/deepujain/skippy.git
cd skippy
./scripts/verify-skill-layout.shAttach Skippy Mode and the target project skill when one exists. For merge-request queue work on external repositories, also attach contribution quality.
MIT License. See LICENSE.