8000 GitHub - alamops/skills · GitHub
[go: up one dir, main page]

Skip to content
alamopsPublic

About

No description, website, or topics provided.

Resources

Stars

53 stars

Watchers

0 watching

Forks

Latest commit

 

History

37 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

alamops/skills

A personal, open-source collection of Agent Skills — installable as a Claude Code plugin or via npx skills into any compatible agent.

License: MIT Agent Skills Claude Code Plugin npx skills


What's a skill?

A skill is a folder containing a SKILL.md file with instructions an agent loads on demand. Think of it as a reusable, portable prompt: when this scenario comes up, do these things. Skills follow the Agent Skills open standard, so a single skill works across Claude Code, Codex, Cursor, Gemini CLI, and dozens of other agents.

This repo is a curated, personal collection. Each skill is small, focused, and written for general reuse — fork what's useful, ignore the rest.

Compatibility

Channel How to install Works with
Claude Code marketplace /plugin marketplace add alamops/skills Claude Code — recommended for Claude Code
npx skills CLI npx skills add alamops/skills Codex, Cursor, Gemini CLI, Continue, Cline, Aider, and 50+ more — plus Claude Code, with the caveat below
Manual Copy any skills/<name>/ folder into your agent's skills directory Any agent that follows the SKILL.md spec

Claude Code users: install via the plugin marketplace, not the npx skills CLI. The CLI keeps one canonical copy of each skill in ~/.agents/skills/ and symlinks it into each agent's own folder (~/.claude/skills/ for Claude Code). Claude Code only reads ~/.claude/skills/, and there are open CLI bugs where the skill lands in ~/.agents/skills/ but the ~/.claude/skills/ symlink is never created — so it "installs" yet Claude Code can't see it (#744, #693, #851). The plugin writes straight into Claude Code and doesn't depend on symlinks.

Install

Claude Code (whole bundle as a plugin)

/plugin marketplace add alamops/skills
/plugin install alamops-skills@alamops-skills

Skills are then invokable as /alamops-skills:<skill-name> (or auto-triggered from the description).

Any agent (via npx skills)

Works with Codex, Cursor, Gemini CLI, and the 50+ other supported agents — and with Claude Code, though the plugin above is more reliable there (see the Compatibility caveat).

First, list everything available in the repo:

npx skills add alamops/skills --list

Then target a specific agent with --agent, and pass --skill '*' for every skill (or --skill <name> for one). Instructions for the two most common agents:

Codex

# Every skill
npx skills add alamops/skills --skill '*' --agent codex

# A single skill
npx skills add alamops/skills --skill <skill-name> --agent codex

Codex reads skills from ~/.codex/skills/ (global) or .agents/skills/ (project).

Claude Code

Prefer the plugin marketplace — it's the reliable route on Claude Code. Use the CLI only if you specifically want per-skill installs.

# Every skill
npx skills add alamops/skills --skill '*' --agent claude-code

# A single skill
npx skills add alamops/skills --skill <skill-name> --agent claude-code

Claude Code reads skills only from ~/.claude/skills/ (global) or .claude/skills/ (project). Verify the install actually linked — run npx skills list -g (or check that those folders contain the skills). A known symlink bug can leave skills stranded in ~/.agents/skills/ where Claude Code never sees them; if that happens, use the plugin instead.

Avoid --all on Claude Code. It installs to all detected agents non-interactively and relies on the same symlink step that the bug above breaks. Target --agent claude-code explicitly, or use the plugin.

The CLI keeps one canonical copy of each skill under ~/.agents/skills/ (or .agents/skills/ for a project-scoped install) and symlinks it into each targeted agent's directory. See vercel-labs/skills for full options.

Skills

Skill Description Tags
code-review Read-only review of any change source — PR, branch diff, working tree, recent commits, or code from the conversation — plus re-reviews that score a fix round; checks wiring into production, claims vs code, trust boundaries, behavior under the real deployment shape, and whether tests can fail, against the repo's own rules review, quality, security, performance
appstore-review Read-only pre-submission audit against the live Apple App Store Review Guidelines and Apple Developer News — fetches both as exact text, fans out parallel sub-agents per guideline section plus a build/upload/device lane (SDK minimums, scene life cycle, iPhone Duo), returns rejection-risk findings keyed by rule number with upcoming deadlines and an App Store Connect checklist, 8000 or a clean verdict review, ios, app-store, compliance, mobile
appstore-seo App Store & Google Play ASO plus Apple Ads planning — pulls the live listing and competitor shelf from Apple's public endpoints, mines keywords against real search data, allocates the indexed character budget, emits character-checked fields (UTF-16, the way App Store Connect counts), covers the 2026 creative surfaces (search-result asset, product page header, iPhone Duo screenshots) and custom product pages as organic keyword routing, then turns the same research into a Brand/Generic/Competitor/Discovery campaign plan with negatives aso, app-store, google-play, apple-ads, seo, marketing, mobile
to-prd Drafts a Product Requirements Document from a description, conversation, provided files, media, or a whole repo (forward or reverse-engineered from existing code) — asks clarifying questions first, saves to docs/ product, prd, planning, requirements
create-tasks Senior Technical PM that turns a PRD, brief, or conversation into a small set of deep, end-to-end dev/QA tasks — performs mandatory deep repo analysis, asks clarifying questions, then writes one Markdown task per file plus a master INDEX.md under docs/tasks/<feature-slug>/ tasks, engineering, tickets, planning, qa
implement End-to-end feature-delivery orchestrator — the session model plans, then fans out background sub-agents through investigate → grill → plan → implement → review → tests → run → fix, with per-phase model/harness routing in AGENTS_CONFIG.yml (multi-harness per step supported) orchestration, agents, implementation, planning, tests
investigate implement's Phase 1 on its own — parallel read-only research over the codebase, git history and live docs, plus scratchpad spikes that prove load-bearing assumptions; saves a brief with a completeness inventory of every caller and data surface to docs/plans/<slug>-investigation.md research, planning, blast-radius, spikes
grill implement's Phase 2 on its own — a grounded, hard interrogation of the owner that leaves no load-bearing unknown before planning; asks through a local browser decision form (evidence, options, recommendations beside each question; answers back as JSON) and records each decision with its source and disposition in docs/plans/<slug>-grill.md (--auto self-grills and escalates one-way doors) requirements, planning, questions, edge-cases
write-plan implement's Phase 3 on its own — a decomposition-ready plan with file-disjoint tasks, execution waves, an explicit e2e decision and a completeness ledger, saved to docs/plans/<slug>.md in the format implement/execute-plan run from planning, decomposition, agents
execute-plan implement's Phase 4 on its own — runs a plan's coding waves with parallel agents that never share a file, a no-TODO completeness clause, and a checkpoint commit per wave orchestration, agents, implementation
write-tests implement's Phase 6 on its own — unit/integration/e2e tests partitioned by module, extending the existing harness, run once, with product defects reported rather than bent around tests, e2e, coverage
test-loop implement's Phases 7–8 on its own — runs the whole suite (owning the e2e app lifecycle), triages product vs test vs flake, fixes with file-disjoint agents and re-runs to green without ever skipping or loosening a test tests, e2e, ci, flaky-tests
break-fix Adversarial e2e bug hunt on a running app — attacks it as a hostile, confused and impatient user, watches console/network/server logs rather than the viewport, then root-causes each bug, writes a failing e2e regression test, fixes it, and proves the suite goes green qa, e2e, testing, bug-hunt, regression
business-review Analyzes a product/business from its public-facing materials, generates and ranks buyer personas, recommends an ICP, pressure-tests positioning and pricing, saves strategy artifacts to docs/ gtm, personas, icp, positioning, strategy
rpg-persona Hard buyer-persona roleplay with a coaching block after every reply — pressure-tests pitches, messaging, and pricing, saves the transcript and lessons to docs/ROLEPLAY_NOTES.md. Run business-review first so the roleplay uses real, ranked personas. gtm, sales, roleplay, coaching, objection-handling

A thorough, read-only review of whatever change source you point it at: a pull request, a git diff against a base branch, uncommitted edits in your working tree, recent commits, or code that was just produced in the conversation. It produces findings and never edits code. Every review is pinned to a head and base SHA and says what it didn't run (CI, migrations, plan/apply). Before judging anything, it reads the repo's own rules: CLAUDE.md/AGENTS.md, lessons-learned files, incident write-ups, ADRs, checklists, the tech-debt register. A change that repeats a documented lesson gets cited by file and line.

It spends most of its effort where expensive defects hide, which is outside the changed lines:

  • Wired, not just written. Checks every new export, route, job type, config key and metric for a production caller reachable from an entry point. It also traces each output the change exists to produce back to the code that creates it. It flags code that's tested but never called, production stubs, and config that's parsed but never read.
  • Claims audit. Checks the PR body, plan ledger, generated reports, commit messages and test names against the code at head.
  • Security & trust boundaries. Tenant isolation and authz gaps. Lookups not scoped to their exact subject. Privilege granted for one item but applied to a batch. Approvals not bound to the version the approver saw. Untrusted parties that can declare their own validation facts or drive terminal state. Path and size confinement, the pre-auth surface, fail-closed production config, kill-switch precedence, and RLS self-recursion.
  • Reliability under the real deployment shape. Two instances and rolling deploys, ownership checks on broadcasts, network calls inside transactions, pool self-deadlock, unsupervised loops, retries without caps or idempotent re-creation, and cleanup parity across every path that ends a resource.
  • Test quality. Asks whether each test would fail if the bug it names came back. Flags assertions a constraint already guarantees, loops over empty sets, "two-process" tests run in one process, and helpers that silently pass when the database is missing.
  • Performance, consistency and structure. In-memory aggregation, sequential fan-out, enum and validation drift, schema↔code column drift, one writer per state, the composition root staying wiring, and size limits.
  • Infra and runbooks, when they're in the diff. Ordering against silent rollbacks, permission semantics, positive controls for every alarm, targeted prod applies, runbook steps that reference real artifacts, and cross-repo merge order.
  • Blast radius. Callers, sibling paths, downstream flows, stale state.

Every review starts with the bundled scripts/quality_gates.py. It runs in seconds even on a 30,000-line diff and has two checks. wiring lists new exports nothing in production reaches, and config keys that are parsed but never read. hygiene flags patterns in the added lines: laptop paths and chat links cited as specs, silent test guards, fail-open secret checks, non-constant-time compares, floating promises, unguarded async intervals, unordered LIMIT 1, env reads outside config, literals duplicating config defaults, and commits whose message doesn't fit their size. Its output is a list of leads to confirm, not findings. Large diffs then split into parallel read-only passes of two kinds. Dimension passes each take one concern (architecture, security, reliability, test quality, operations). Correctness passes take one subsystem or flow each, catching the logic bugs no cross-cutting checklist owns. Every blocker and must-fix is re-verified by hand before it's reported. Re-review mode scores each earlier finding as fixed, partial, not fixed or regressed at the new head. It then looks for what the fix round introduced: a new path around the guard, an anti-pattern reintroduced on a new entity, a regression test that was never red for the bug, or docs describing an older head.

Each finding has an ID (B1, M1, S1, …; prefixed R- when the codebase uses the same shape), one defect per ID, and a blocker / must-fix / should-fix / nit severity calibrated by how often it fires in the real configuration. Each also has file:line, a mechanism, a concrete failure scenario and a fix. The report leads with what the change does, what needs attention, and a verdict (approve / request changes / comment). Findings follow, then questions only the author can answer. On a large review it adds a short Keep list of patterns the fix round must not break, and a proposed PR split when the change is too big to review. The full checklists live in references/.

Install just this skill into any compatible agent:

npx skills add alamops/skills --skill code-review

Trigger it by asking any agent (or Claude Code with the plugin installed) for a "code review", "PR review", "diff review", "feedback on pending or recent changes", or "review the code we just wrote" — the skill auto-loads from the description.

A pre-submission audit that checks an iOS-shipping project against the current Apple App Store Review Guidelines and the submission requirements Apple publishes around them — and pulls both live from developer.apple.com on every run, so it never reviews against a stale snapshot in the model's head. Apple's rules drift several times a year (hidden-feature bans, third-party-AI consent, US purchase-link carve-outs, ATT, privacy manifests, account-deletion mandates), and a second set of requirements never appears in the guidelines at all: SDK and deployment-target minimums enforced at upload, age-rating questions, new hardware. When iPhone Duo shipped in October 2026 the guidelines didn't mention it — the requirements (Duo screenshots mandatory from April 2027, iOS 27 SDK builds that won't launch without the scene life cycle) were in Developer News and release notes. If the live fetch fails, the skill aborts rather than guess.

How it works:

  • Detects the project shape — native iOS (Swift/SwiftUI/UIKit/Xcode), React Native, Expo, Flutter, Capacitor/Ionic, or Unity — then builds a Project Profile (payment surface, tracking SDKs, auth providers, UGC, kids-category signals) so it only flags rules that actually apply.
  • Fetches exact text, not a summary. A bundled stdlib script (scripts/fetch_sources.py) curls the guidelines, a year of Apple Developer News and the Upcoming Requirements page, slices the guidelines per section for the lanes, and prints any single rule verbatim (--rule 5.1.2) so every cited number is checked against today's wording.
  • Fans out parallel sub-agents across the five guideline sections (Safety 1.x, Performance 2.x, Business 3.x, Design 4.x, Legal 5.x), a Build, upload & device lane (Xcode/SDK and deployment-target minimums, launch screen, scene life cycle for iOS 27 SDK builds, iPhone Duo layout and screenshot readiness), and two cross-cutting lanes — App Privacy / required-reason APIs and App Tracking Transparency — each scoped to just its slice of the live text. Tracking lanes are skipped (and the skip is reported) when no tracking surface exists.
  • Cross-checks the common deal-breakers Apple rejects on weekly: account creation with no in-app deletion (5.1.1(v)), a social login with no equivalent privacy-preserving option (4.8), personal data sent to an AI provider without consent (5.1.2(i)), digital goods paid inside the app outside IAP (3.1.1 — with the United States purchase-link carve-out handled per storefront), features hidden behind remote flags during review (2.5.19), ATT prompt vs. NSUserTrackingUsageDescription mismatch, missing usage descriptions or PrivacyInfo.xcprivacy, a pinned toolchain below the upload minimum, and leftover TestFlight/beta gates in the production path.

Output is a verdict (✅ likely pass / ⚠️ risk / 🛑 will be rejected) followed by findings grouped by severity, each keyed to a guideline number with Evidence (file:line or absent: <thing>), the live rule quote, Why it fails, and a concrete Fix — then Upcoming requirements (dated, not yet enforced) and a Check in App Store Connect list for what the repo can't show. Requirements that live outside the guidelines are cited by their Apple source, never filed under an invented rule number. It never modifies code.

Install just this skill into any compatible agent:

npx skills add alamops/skills --skill appstore-review

Trigger phrases: "run an App Store review", "App Store readiness check", "pre-submission audit", "will Apple reject this?", "is this 4.8-compliant?", "I added Google sign-in — am I OK?", "is my app ready for iPhone Duo?", an ITMS upload error, or asking whether a specific change (moving subs off IAP or to a web link, adding an analytics SDK, sending user data to an AI API, a new permission) is allowed. For a general bug/perf/security review, use code-review instead; for implementing a feature (Sign in with Apple, IAP, ATT), this skill audits, it doesn't build.

App Store Optimization for both stores, run as an engineering task rather than a copywriting one. Most ASO advice is folklore, and it fails on iOS for a structural reason: Apple does not index the description at all. Rank comes from a handful of indexed fields with tiny budgets (name 30 / subtitle 30 / keywords 100), and Apple builds search phrases by combining tokens across them — so every repeated word is a wasted character. Google Play is the opposite: its long description is indexed, so the same copy can't serve both stores.

It also treats Apple Ads as part of the same job, because it is: Apple judges ad relevance for a keyword partly from your product page metadata, so the 100-character keyword field is what keeps your cost per tap down — and in the other direction, the Search Terms report is the only record of queries real users actually typed, while the keyword popularity score (1–100) is the only genuine volume figure that exists anywhere. The same research therefore produces both the listing and the campaign plan.

Three modes: audit an existing listing, generate a full field set pre-launch, or audit → rewrite (the common one — never rewrites blind when a live listing exists).

How it works:

  • Pulls ground truth, never audits from memory. Documented recipes hit Apple's public endpoints — the iTunes lookup API, the store-page JSON (for the subtitle, which the API doesn't expose, and the genuine "You Might Also Like" shelf with competitor subtitles — the cheapest competitive keyword corpus there is), and the reviews RSS for the vocabulary real users type. Explicit that the keyword field is private and that Play has no public API. Only the "You Might Also Like" shelf counts as competitors — the developer's own sibling apps on the same page are excluded.
  • Mines keywords against live search. For each candidate term, the Search API gives a difficulty score from the top-10 rating counts, an intent signal, and whether your app ranks at all — so keyword choices are argued from store data. It deliberately refuses to invent a search-volume number: result depth doesn't proxy for volume, and a guessed metric presented as data poisons the whole deliverable.
  • Checks every field before you see it. A paste-and-run checker counts in UTF-16 code units the way App Store Connect does (an emoji costs 2), hard-fails on over-limit fields, keyword-field syntax, competitor trademarks and Play's 5-tag cap, and flags the expensive strategy mistakes — words duplicated across name/subtitle/keywords, category names and filler burning keyword budget, unused characters, iOS keyword stuffing, Play keyword density outside 2–5 mentions, boilerplate release notes. It's stem-aware, catching scan in the keyword field while the name says Scanner — a wasted repeat exact-string comparison never sees.
  • Checks the name against what's already live — exact collisions with shipping apps and how many already lead with your brand token. A name collision outranks anything in the keyword field — it splits brand search and risks rejection under 4.1 (copycats) or a 5.2 trademark complaint.
  • Covers conversion, not just ranking — icon legibility, the first three screenshots (most visitors never scroll), the 2026 surfaces (the search-result creative asset that replaces screenshots 1–3 for iOS 27+ users, the product page header, the iPhone Duo screenshot set and its badge), App Review's "more than half the screenshots show the app" rule, muted-safe previews, ratings strategy, and a Product Page Optimization / Play experiment plan with a recorded baseline. Custom product pages are planned as keyword routing — up to 70 pages, each able to own a cluster of organic keywords from the approved keyword field.
  • Builds the Apple Ads plan from the same keyword table. The scored terms bucket into the four campaigns that have genuinely different economics — Brand (defensive, cheapest, highest-converting), Generic, Competitor, and Discovery (whose job is finding queries you didn't think of) — plus the negative keyword lists, the step teams skip and the reason campaigns look unprofitable when they aren't. It encodes the asymmetry people get backwards: competitor brand names are standard in Apple Ads and forbidden in the organic keyword field — same word, opposite rule.

Output is both: copy-paste-ready blocks with live character counts in chat, and durable artifacts under docs/appstore/ — audit.md (a 5-dimension, 100-point scorecard), keyword-research.md (the scored table plus the terms rejected and why), metadata.<locale>.md per locale, creative-brief.md, apple-ads.md (campaign map, negatives, custom-product-page mapping, and the 4-week loop that mines the Search Terms report back into the listing), and experiments.md.

The skill has no runtime dependency — no bundled scripts, no libraries. Every mechanical step (pulling the listing, scouting keyword difficulty, checking name collisions, counting UTF-16 characters, bucketing the ad plan) is documented in reference files as paste-and-run standard-library Python that talks to Apple's public endpoints, so it runs anywhere and degrades to by-hand steps where code can't run.

Install just this skill into any compatible agent:

npx skills add alamops/skills --skill appstore-seo

Trigger phrases: "improve my app store ranking", "nobody finds my app in search", "review my App Store listing" with an ID or link, "write our store listing before we launch", keyword research for an app, competitor listing teardowns, localizing a listing, planning a store A/B test, or planning Apple Ads keywords and campaign structure. Ongoing bid and budget management of a live ads account is deliberately out of scope — the skill sets the structure that bidding operates inside. For whether Apple will reject the app, use appstore-review — that one audits compliance, this one audits discovery and conversion.

A senior-CPO collaborator that turns any combination of inputs — a feature/product description, the conversation thread, a small set of provided files, attached media, linked docs, or an entire repository — into a complete Product Requirements Document. Works in two modes: forward (PRD for something you're about to build, repo as enrichment) and reverse (PRD for something already built, repo as the primary source). It clarifies before drafting — surfacing missing personas, undefined success criteria, unclear flows, ambiguous scope, and unstated constraints — then writes a structured Markdown PRD covering:

  • Executive summary, problem, goals & non-goals.
  • Personas, scenarios, and user journeys.
  • Functional requirements — numbered, testable, with flows and business rules.
  • Non-functional requirements — performance, security, privacy, scalability, reliability, usability, observability.
  • Timeline & milestones — phased delivery with exit criteria.
  • Success metrics — primary KPIs with baselines and targets, plus feedback mechanisms.
  • Risks & mitigation — product, delivery, technical, operational, with owners.
  • Blast-radius & cross-feature impact — affected features, integrations, downstream systems, data assumptions.
  • Stakeholders — RACI roles.
  • Assumptions and open questions — captures anything the user declined to clarify, plus any inferred behavior in reverse mode.
  • Appendices and glossary.

The PRD is saved to docs/<unique-name>.md. In forward mode the skill stays shallow on the repo (enrichment only); in reverse mode it walks user-visible entry points and behavior at the product layer. It never modifies code.

Install just this skill into any compatible agent:

npx skills add alamops/skills --skill to-prd

Trigger it by asking any agent (or Claude Code with the plugin installed) to "write a PRD", "draft a product requirements doc", "create a feature spec", "scaffold a PRD for X", or "reverse-engineer a PRD from this repo / these files" — the skill auto-loads from the description.

A senior Technical Product Manager that turns a PRD, feature brief, ticket, conversation thread, or set of provided docs/media into a small set of deep, end-to-end, implementation-ready development and QA tasks. Performs mandatory deep repository-context analysis — entry points, data layer, reusable utilities, API/UI patterns, sibling code paths, tests, observability, and (when applicable) App Store / Google Play constraints — before drafting anything. Surfaces unknowns as one structured pass of clarifying questions, plans the task list with the user, then writes each task as its own Markdown file. Each task is genuinely end-to-end (no backend-only / frontend-only splits) an 8000 d self-sufficient across all required layers:

  • Problem / Motivation and Business Rules — numbered, testable.
  • Technical Goals and Dependencies (upstream / downstream / cross-team).
  • Files to Modify (with exact paths from the repo) and Related Existing Code (utilities, services, components to reuse).
  • Architecture Notes with Mermaid diagrams when complexity warrants.
  • Data Model — schemas, fields, constraints, indexes, migrations.
  • API Specs — endpoints, methods, request/response schemas, error codes, auth, idempotency.
  • Non-Functional Requirements — performance, security, scalability, tenant isolation, reliability, atomicity, observability, validation, event-driven correctness, mobile platform compliance.
  • Implementation Guide — numbered steps grounded in the cited files and utilities.
  • Error Handling — client-facing vs log-level, ownership failures, truncation, enum consistency, mutual-exclusion.
  • Blast-Radius & Impact Analysis — callers, sibling paths, retries, recovery, stale state, downstream systems.
  • Testing Strategy — unit / integration / e2e coverage, fixtures, negative paths.
  • Acceptance Criteria and QA Testing Steps — measurable, with explicit manual scenarios.
  • Design Specifications — screens, states, components, accessibility, localization, with associated images.
  • Open Questions — anything still unresolved at write time.

Each task title carries a layer prefix ([Full-Stack], [Backend+DB+Tests], [Frontend+Backend+Tests], [DevOps], [Mobile+Backend+Tests], etc.) so reviewers can tell the scope at a glance. No time, effort, story-point, or staffing estimates — tasks describe what and how, not how long or who.

Outputs save under docs/tasks/<feature-slug>/:

  • INDEX.md — execution-order list with prefixes, layers, dependencies, and shared assumptions/open questions.
  • 001-<slug>.md, 002-<slug>.md, … — one task per file, indexed by execution order.

The skill is read-only on source code.

Install just this skill into any compatible agent:

npx skills add alamops/skills --skill create-tasks

Trigger phrases: "create dev tasks", "break this PRD into tasks", "scaffold engineering tickets", "generate QA tasks", "turn this spec into implementation tickets", "create tasks for sprint X."

Recommended product → engineering workflow

  1. to-prd — produce the PRD (docs/<feature>-prd.md), surfacing personas, requirements, success metrics, and risks.
  2. create-tasks — turn that PRD plus a deep repo scan into the task set under docs/tasks/<feature-slug>/.
  3. implement — orchestrate the actual build: investigate, grill, plan, then fan out background agents to code, review, and test each task. (Or run any single phase on its own: investigate, grill, write-plan, execute-plan, write-tests, test-loop.)
  4. code-review — review each PR as engineers ship the tasks; feed any structural findings back into the next task set.
  5. break-fix — once the feature is running, hunt it adversarially for the bugs a diff review can't see (state, timing, session, real-user misuse), and leave a regression test behind for each one.

An end-to-end feature-delivery orchestrator. Invoked as /implement <task>, the current session model stays in the driver's seat — it does the thinking (synthesis, interrogation, planning, decomposition, merge decisions) and delegates the parallelizable labor to background sub-agents whose models are chosen per phase in AGENTS_CONFIG.yml. It runs eight phases:

  1. Investigate — the orchestrator decides how many read-only agents to spawn and fans them out in parallel across the codebase, git history, and (when web tools are available) current best practices.
  2. Grill & confirm — a hard, respectful interrogation of the owner to resolve every load-bearing unknown before planning, asked through the decision form (below). First hard gate; runs on every delivery, self-answered on the record under --auto.
  3. Plan — a complete, decomposition-ready plan saved to docs/plans/<feature-slug>.md, whose work breakdown partitions the feature into file-disjoint tasks and execution waves. Presented for explicit approval — second hard gate.
  4. Implement — one background agent per task, launched in waves, each with a self-contained brief and an exclusive set of files so parallel agents never collide (worktree isolation when clean partitioning isn't possible).
  5. Code review — reviews the diff using the code-review skill as the rubric when it's installed, else a built-in review rubric bundled in the skill (so /implement stays fully standalone); the orchestrator triages must-fixes.
  6. Tests creation — the same collision-free fan-out, partitioned by module under test.
  7. Tests running — a single background agent runs the suite and reports pass/fail.
  8. Tests fixes (conditional) — fix agents for failures and must-fix findings, then re-run to green.

Per-phase model/harness routing lives in AGENTS_CONFIG.yml at the repo root. Each phase resolves to one or more runners: the orchestrator itself (self), a Claude sub-agent (opus/sonnet/haiku/fable), or an external CLI harness (Codex, Gemini, Aider, …) via a shell command template. Listing multiple harnesses per step — e.g. haiku + gpt-5.4-mini on implementation — either distributes independent tasks across them or races the same task and keeps the best, per the phase strategy. Missing external CLIs fall back to a Claude sub-agent automatically.

Delivery runs accept modifier flags, combinable with each other and the task text: /implement --auto <task> runs unattended for remote/CI execution, /implement --no-e2e <task> skips the end-to-end test layer (unit/integration coverage still runs), /implement --no-spikes <task> skips Phase 1's validation spikes (unsettled load-bearing assumptions are surfaced as open questions instead of experimentally verified), and /implement --no-follow-ups <task> removes the owner's option to defer remainder to a later ticket (any of --no-follow-ups, --no-follow-up, --no-followups, --no-followup, --nofollowups, --nofollowup selects it).

Completeness is the default; --no-follow-ups is the stricter contract. The usual way a delivery ends up almost right is a remainder: three of seven call sites still on the old path, the empty state left as a TODO, the enum grown in the model but not the validator, a migration that adds the column and never backfills the rows. Every run therefore carries a completeness ledger in the plan — each candidate follow-up marked in this run (with the owning task), out of scope (with why it's a different ticket), or owner-deferred (with who decided it at the grill or approval gate). Agents never defer on their own: implementation briefs ban TODO/stub placeholders and route out-of-bounds remainder back to the orchestrator, and the code review treats completeness findings as correctness, i.e. must-fix. What the owner may still do by default is consciously push a piece to a later ticket. --no-follow-ups removes that option too — the ledger has to close with nothing owner-deferred — which is also what makes it meaningful under --auto, where there's no owner to defer in the first place. Neither the default nor the flag is a scope expansion: adjacent features, drive-by refactors, --no-e2e/--no-spikes overrides and one-way decisions under --auto stay out, and a sweep that dwarfs the original ask goes to the owner at the approval gate rather than being absorbed silently.

Done means wired, and claims match evidence. A unit that's written and unit-tested but never reached by a production entry point isn't done. Each plan task names what wires it in (wired by), and each success criterion names the production path that produces it. Phase 4 ends with a wiring audit: every new export traced to a caller, plus config keys with no reader and production stubs. The plan also names its invariants (who may trigger each privileged action, one writer per state, what an approval binds to) and the single place each is enforced, so new paths route through it instead of re-implementing it. The contract lives in the repo: a spec cited from someone's machine or a chat link is saved under docs/specs/ and committed unamended before any code, and later amendments go to a human to approve. The report, PR body and any generated summary are written last, from the final run and the final head. Prevention, not just detection. Every coding brief carries three things.

  • The plan's invariants and runtime shape, pasted verbatim.
  • The build rules for what the task touches. These are the review's checklists turned into rules for writing code. They're picked by the task's risk tags: trust, data, external, concurrency, state, migration, infra or tests.
  • A self-check the agent runs before reporting. It re-reads its own diff, walks each flow end to end (failure states and command sequences included), runs quality_gates.py on its own files with --paths, runs the narrowest typecheck and tests, and gives evidence per acceptance scenario.

The orchestrator then reads each task's diff against its acceptance instead of trusting the summary. It reviews any wave holding a risky task before the next wave builds on it. And it refuses off-plan "passes" until they're written into the plan.

Runs that answer an outside review follow the same rules plus a finding map. Each finding gets a regression test observed red for the bug, every path into the guarded action is re-traced including the ones the fix adds, and each finding's status is honestly fixed, partial or not fixed.

The two human gates are enforced, and --auto is the only way off them. Autonomy is declared, never inferred — a detailed ticket, a confident read of the task, or being spawned by another agent are not signals that the owner left, so the grill happens whenever there's any channel to reach one. --auto doesn't delete Phase 2; it changes who answers: the orchestrator writes the full question set first, then answers each from the strongest source available (spike evidence → repo convention → ecosystem default → judgment), takes the reversible option wherever it's down to judgment, and records the exchange as a question / answer / source / confidence table in the plan so the absent owner can audit every call. Genuinely one-way decisions — destructive migrations, public API contracts, auth boundaries, anything touching money or secrets — are scoped out of the run and escalated rather than guessed.

On the first /implement run with no config, the skill runs a short guided setup (pick a balanced / fast / quality preset, optionally plug in an external harness) and writes AGENTS_CONFIG.yml. Re-run setup anytime with /implement --config. See assets/AGENTS_CONFIG.example.yml and references/agents-config.md for the full schema.

Install just this skill into any compatible agent:

npx skills add alamops/skills --skill implement

Trigger phrases: "/implement", "build this feature end-to-end", "orchestrate the implementation", "plan and implement X", "run a multi-agent build", "/implement --config", "/implement --auto X", "/implement --no-e2e --no-spikes X", "/implement --no-follow-ups X", "/implement --nofollowup X", "finish this completely, I don't want a follow-up PR".

Running implement's phases à la carte

Each delivery phase is also its own skill, for when you want one step rather than the whole loop — investigate a change without committing to build it, get grilled on a spec, hand a plan to someone else, or just get a red suite green. implement itself is unchanged and self-contained; these are standalone extracts that run on the session's native sub-agents (they don't read AGENTS_CONFIG.yml — per-phase model and harness routing stays an implement feature).

Phase Skill Reads Writes
1 investigate the ask docs/plans/<slug>-investigation.md
2 grill the investigation, if any docs/plans/<slug>-grill.md
3 write-plan investigation + grill, if any docs/plans/<slug>.md
4 execute-plan the plan code on a feature branch, one commit per wave
5 code-review the diff findings
6 write-tests the plan's test tasks, or the branch diff tests
7–8 test-loop the suite, plus any must-fix review findings fixes, until green

Every step works without the ones before it — each grounds itself when there's no prior artifact — and the artifacts share a slug, so a later step (or a later session) finds what an earlier one left. The plan format is the one implement writes, so /implement can pick up a write-plan plan and drive it the rest of the way.

Ground truth before anyone plans. Fans out read-only research agents in parallel — codebase (entry points, sibling paths, utilities, how the app runs, the e2e harness), git history (prior attempts, reverts, recent churn), and live library docs — then runs spikes: the smallest throwaway code, confined to the scratchpad, that proves or disproves an assumption reading can't settle ("does Intl format BRL correctly on our Node?" gets a command and its output, not an opinion). Synthesizes what we know / proved / assume / must ask, a completeness inventory (every caller including re-exports and scripts outside src/, every propagation point, existing data a migration must backfill, docs that describe current behavior), and the runnability picture. It also returns the repo's own standards that apply (lessons-learned, incidents, ADRs, checklists, sibling layout), the runtime and trust shape (instances, deploys, who can send input and what they can reach), where the spec lives (flagged if it lives outside the repo), and live facts checked with read-only queries. Read-only on source; --no-spikes turns the experiments into explicitly unverified questions.

npx skills add alamops/skills --skill investigate

Trigger phrases: "investigate X before we build it", "map the blast radius of this change", "find every call site this migration touches", "is this approach feasible here — prove it", "research only, no spikes".

A hard, respectful interrogation of the owner, grounded in the code first so it never asks what the repo already answers. Presses in one or two structured passes on scope, business rules, edge/error/permission states, data and contract changes, budgets, rollout, the acceptance bar — and every would-be follow-up, each dispositioned in this change, out of scope, or owner-deferred (removed by --no-follow-ups). It also covers trust and approvals (who may trigger each privileged action, what an approval binds to), the runtime shape (instances, rolling deploys, crashes mid-step, the kill switch), and where the spec lives. Offers recommended defaults so answering is cheap, pushes back on vague answers, and leads with evidence rather than asking about settled facts.

Questions go to the owner as a decision form, not a chat question tool. A one-line question with three labels makes the owner decide blind. The form is a local web page that shows every question beside what it takes to decide it: the evidence with file:line and the exact lines, the options and what each one does to the plan, the recommendation and why, an impact badge, and a one-way-door flag. The owner answers by single or multi choice, ranking, text, number, confirm-or-override, or file upload. Follow-ups appear only when an earlier answer makes them relevant, Accept recommendations fills the defaults in one click (never the one-way doors), and drafts survive a reload. The agent gets answers.json back, with each answer's status, whether it matched the recommendation, notes, and a summary of overrides and unanswered one-way doors. It's harness-agnostic: a zero-dependency Node script (scripts/decision_form.mjs) validates the agent's questions.json, serves the page on 127.0.0.1 behind a per-run token, and exits when the owner submits. Where no browser can reach the agent's machine, build makes an offline HTML copy whose download import turns into the same JSON. The questions and answers are committed next to the decision record as evidence of what the owner was shown and what they chose. implement's Phase 2 ships the same kit. A skipped question is never treated as an answer: it comes back to the owner in the next round, and the grill isn't finished until every required question is answered. Only the owner saying in their own words "stop asking, decide the rest" turns the remainder into recorded assumptions, and even then the one-way doors are recorded as unratified, never answered on their behalf. --auto grills with nobody there: writes the full question set first, answers each from evidence → repo convention → ecosystem default → judgment with a confidence mark, takes the reversible option, and escalates one-way doors instead of guessing.

npx skills add alamops/skills --skill grill

Trigger phrases: "grill me on this before I build it", "poke holes in this spec", "what am I missing?", "interrogate me on the open questions", "ask me the hard questions — don't accept vague answers".

Turns an understood change into a plan parallel agents can execute without colliding. Builds the completeness ledger first and lets it feed the breakdown, then partitions the work so no two tasks in a wave own the same file (watching the hot spots that quietly break a partition — registries, barrels, lockfiles, migrations, shared fixtures), orders the waves by dependency, and decides e2e applicability explicitly with a run recipe. Every task names what wires it in to production, carries risk tags that pick its coding agent's build rules, and states acceptance as checkable scenarios: failure states and command sequences included, each with how it's proven. Every success criterion names the path that produces it. Invariants get one enforcement point each, oversized changes are planned as a stack of PRs, a spec that lives outside the repo is copied into docs/specs/, and a plan that answers a review carries a finding map. Saves to docs/plans/<slug>.md in implement's template and presents it for approval; changes no code.

npx skills add alamops/skills --skill write-plan

Trigger phrases: "write an implementation plan for X", "break this into parallelizable work", "plan this change before we code it", "turn this spec into an execution plan".

Runs a plan's coding waves — just the code. Cuts a branch and records the base SHA, validates each wave's file ownership before spawning, briefs every agent with its owned files and a completeness clause (no TODO/stub standing in for in-scope work; remainder outside its files comes back to the coordinator instead of becoming a marker), holds the barrier between waves, and commits a checkpoint per wave so a failure resumes from the last green one. Briefs also carry a wiring clause, a use-what-exists clause (config, state machines, the plan's gates), the plan's invariants, the build rules for the task's risk tags, and a self-check the agent must run and report evidence from. The coordinator verifies each task's diff against its acceptance rather than trusting the summary. It reviews risky waves before the next wave builds on them, and rejects off-plan work until it's in the plan. Commit messages are written from the actual diff, and the run ends with a wiring audit so nothing ships tested but unreachable. Stops before review and tests — follow with code-review, write-tests, test-loop, or use implement for the whole loop.

npx skills add alamops/skills --skill execute-plan

Trigger phrases: "execute this plan — just the code", "run the waves in docs/plans/X.md", "fan these tasks out to agents".

Writes the tests a change needs from its intent (plan, ticket, PR), not just its diff — unit, integration, and e2e whenever the change crosses a process boundary, with "not applicable" recorded as a decision rather than an omission. Extends the existing harness and fixtures, partitions agents by module under test, keeps e2e deterministic, and runs every new test once — then proves each can fail against the specific mechanism its name promises. Requires an assembled-flow test per output, every variant of a new union, negative paths at trust boundaries, the real failure mechanism (two OS processes, SIGKILL), and loud skips instead of silent passes when a service is missing. A test that exposes a real product bug stays failing and gets reported with evidence — never loosened or skipped to go green.

npx skills add alamops/skills --skill write-tests

Trigger phrases: "write tests for the changes on my branch", "add e2e coverage for checkout", "backfill tests for this module".

Runs the whole suite and drives it to green. Owns the e2e lifecycle itself (install, start services, seed, boot the app and wait for real readiness, run headless, keep traces, tear down) and hands back only what genuinely can't be automated, as a precise runbook. Triages before fixing — clusters failures by root cause, re-runs e2e once to separate flakes from defects, decides whether the product or the test is wrong, and separates pre-existing failures from ones the change caused — then fixes with file-disjoint agents and re-runs everything, capped at three rounds. "The suite" includes CI's static gates. Green is checked for being real: skip counts, 0 ms layers, missing services, test-count drops. A review finding is fixed only with a regression test observed red for the bug, every path into the guarded action re-traced, and an honest fixed / partial / not fixed status. Skipping, deleting, loosening assertions, and blind snapshot updates are off the table.

npx skills add alamops/skills --skill test-loop

Trigger phrases: "run the tests", "CI is red — get it green", "fix the failing/flaky tests", "fix these review findings and re-run".

An adversarial bug hunt against the running app, followed by a real fix. Most testing walks the happy path the developers already walked a hundred times while building the feature — it's green by construction. This skill does the opposite: it deliberately violates the contract the UI implies, then closes the loop on whatever falls out.

  1. Scope & safety — confirms a local/dev/staging target, two test accounts (cross-account checks need them), and what's off-limits (anything wired to real money, real messages, or shared data).
  2. Recon — boots the app, finds the existing e2e harness (Playwright / Cypress / Detox / supertest — before finding bugs, so their tests have somewhere to go), maps the surface, then reads the code for assumptions worth attacking: unguarded parseInt on query params, lookups that never filter by owner, client-only validation, index-as-key.
  3. Hunt — runs each surface past eight bad users: the impatient one (double-submits, Back mid-spinner), the confused one (deep-links into step 3 of a wizard), the clipboard (12KB paste, emoji-only name, a leading =), the polyglot (RTL, combining marks, zero-width chars), the multitasker (two tabs, one record), the commuter (offline mid-request, 3G, a request that never resolves), the nosy one (tampered IDs, direct API calls against their own second account), and the extremist (0, -1, 10k rows, year 2999).
  4. Triage — reproduces from a clean state, separates bug from nit / intended / environment, dedupes five symptoms of one missing guard into one root cause, assigns severity by consequence, and checks in before anything architectural.
  5. Root cause — traces one level deeper than the symptom (two orders from a double-click isn't a button bug, it's a missing idempotency guard), greps for every other site with the same defect, and names the broken invariant along with every path that reaches the protected action.
  6. Regression test, red first — writes the e2e test before the fix and observes it failing for the right reason: on its assertion, not because it can't load against the unfixed code, and with the real mechanism (two contexts, two processes, a real kill) rather than a gentler stand-in. A test written after a fix has never demonstrated it can detect the bug; it may be asserting something that was always true.
  7. Fix, green — smallest change that removes the cause, then re-run the test, the manual repro, the full suite (checking it actually ran), and the sibling surfaces (guards frequently narrow a hole rather than close it). Then it attacks the fix itself, since fixes often open the hole next door: a new path that skips the check, checked data stored where the attacker can write, a new state with no exit. Each bug is reported fixed, partial or not fixed. Review findings handed over for fixing start here, one per finding.
  8. Report — docs/bug-hunts/<date>-<slug>.md with repro, evidence, root cause, fix, and test per bug — plus what was attacked and came back clean, which is what tells a reader how much of the app the hunt actually covered.

Bundled references: attack-playbook.md (ready-to-use payloads and step sequences across 13 surfaces — forms, auth/authorization and stale approvals, concurrency, pagination, uploads, network failure, time/locale, direct API, money, background work with restarts and a second instance — plus a signal table mapping console/network/server/database symptoms to their usual cause) and e2e-harnesses.md (per-framework detection, run recipes, attack tooling like page.route and cy.intercept, what to do when there's no harness, and the determinism rules that keep a regression test from being skipped in a month).

Rules of engagement are explicit: authorized local/dev/staging targets only, never production, no irreversible external side effects, no load or infrastructure attacks — "authorization probing" means checking whether your own second account can reach the first one's data.

Install just this skill:

npx skills add alamops/skills --skill break-fix

Trigger phrases: "break my app", "try to break it", "bug hunt", "bug bash", "QA sweep", "exploratory/adversarial testing", "click around and see what explodes", "find bugs by actually using it", "write an e2e test so this can't come back."

A founder-grade GTM analyst that reads a product's public-facing materials (landing page, pricing, onboarding, docs, app/UI, demos), separates marketing language from real buyer value, and produces a strategy package someone could act on this week. It generates 5–8 concrete buyer personas (concrete enough to DM, not "SMB owner"), ranks them across abundance / pain / urgency / willingness-to-pay / retention / strategic leverage, and explicitly distinguishes "most abundant" from "best ICP." Then it pressure-tests the recommendation against alternatives, pricing logic, and friction — and proposes section-by-section changes to messaging, landing page, onboarding, demo strategy, and product experience. Prefers truth over flattery.

Deliverables (saved under docs/ with canonical filenames):

  • CLIENT_PERSONAS.md — full persona dossiers using a fixed template.
  • ICP_ANALYSIS.md — ranking matrix, canonical roles, pressure-test results, primary/secondary/weak-fit recommendation.
  • POSITIONING_RECOMMENDATIONS.md — wrong-vs-right battlefield, headline candidates, section-by-section landing-page changes.
  • PRODUCT_EXPERIENCE_RECOMMENDATIONS.md — onboarding, time-to-value, friction, demo, proof, ranked impact × effort.
  • OUTREACH_DRAFTS.md (optional) — LinkedIn, cold email, social DM for the primary ICP.

Install just this skill:

npx skills add alamops/skills --skill business-review

Trigger phrases: "analyze my business", "generate buyer personas", "find my ICP", "pressure-test my positioning", "review my landing page positioning", "build a GTM strategy doc."

Recommended: run business-review first. rpg-persona is most useful when it's roleplaying a real, ranked persona from your strategy work — not a generic skeptic. If docs/CLIENT_PERSONAS.md and docs/ICP_ANALYSIS.md exist (which business-review produces), this skill auto-picks the strongest skeptical persona and grounds objections in the actual product. Without those docs, the skill will ask you to define the persona before starting, which is slower and less rigorous.

A two-voice sales-pressure-test skill: a skeptical buyer who refuses to make the conversation easy, plus a coach that explains, after every in-character reply, what landed, what missed, which objection was triggered, the buying signals you missed, and what to do next. The buyer demands numbers, rejects vague language ("AI-powered", "10x faster"), pushes on differentiation, pricing logic, switching cost, decision path, and proof — and only closes when you've earned at least three of: differentiation, pricing logic, friction, trust, urgency, decision path.

When the session ends ("end roleplay" / "stop"), the full transcript, coaching summary, strategic lessons, and recommended changes save to docs/ROLEPLAY_NOTES.md.

Install just this skill:

npx skills add alamops/skills --skill rpg-persona

Trigger phrases: "roleplay a buyer", "simulate a sales call", "practice my pitch", "pressure-test my message", "play a skeptical CTO", "objection drill."

Recommended GTM workflow

  1. business-review — analyze the product, generate and rank personas, produce docs/CLIENT_PERSONAS.md + docs/ICP_ANALYSIS.md + positioning docs.
  2. rpg-persona — roleplay against the strongest skeptical persona from step 1 to pressure-test the pitch in conversation; review the saved docs/ROLEPLAY_NOTES.md.
  3. Iterate — feed the lessons from step 2 back into the positioning and product-experience docs, then re-run the roleplay against the next persona.

Skipping step 1 is possible (rpg-persona will ask you to define the persona inline) but reduces the value of the drill — the buyer's objections won't be grounded in your real product or your real ICP.

Project structure

.
├── .claude-plugin/
│   ├── marketplace.json   # Claude Code marketplace catalog
│   └── plugin.json        # umbrella plugin manifest
├── skills/                # all skills, one folder each
│   └── <skill-name>/
│       ├── SKILL.md
│       ├── references/    # long checklists, loaded on demand (optional)
│       └── scripts/       # bundled tools (optional)
├── evals/                 # trigger eval sets per skill, plus the quality-gates regression test
│   ├── <skill-name>/
│   │   └── trigger_eval.json
│   └── quality-gates/     # planted-defect fixture + test for scripts/quality_gates.py
├── tools/
│   └── sync_shared_scripts.py  # keeps shared scripts and references identical across the skills that bundle them
├── LICENSE
└── README.md

A single umbrella plugin (alamops-skills) bundles every folder under skills/. Adding a new skill is one operation — drop a new folder in skills/, and both delivery channels pick it up.

License

MIT — use, fork, modify, redistribute. Attribution appreciated but not required.


Made with care by Alamo Saravali.

About

No description, website, or topics provided.

Resources

Stars

53 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0