Skills

A composable, model-agnostic set of skills for product discovery, shaping, prototyping, task splitting, implementation, human review, project knowledge, test-first development, and safe Git delivery. Install selected skills or the complete plugin.

Choose copy-in installation or the managed plugin.

Copies selected skill folders into your project for local editing.

npx skills@latest add toy-crane/skills

Choose the skills and coding agents to install.

Installs the complete set as a read-only bundle. Updates arrive with new plugin versions.

Inside Claude Code:

/plugin marketplace add toy-crane/skills
/plugin install toycrane-skills@toycrane

Or from your shell:

claude plugin marketplace add toy-crane/skills
claude plugin install toycrane-skills@toycrane

Six skills cover discovery through implementation.

flowchart LR
    DO["discover-opportunity<br/>(no direction yet)"] --> SI["shape-idea<br/>(problem named,<br/>direction rough)"]
    SI --> BP["build-prototype<br/>(judge it by using it)"]
    SI --> SPEC[/spec folder/]
    BP --> SPEC
    SPEC --> ST["split-into-tasks<br/>(multiple deliverables)"]
    SPEC --> IM["implement<br/>(spec folder)"]
    ST --> IM
    IM --> DONE["verified and reviewed"]
    IM -. "uses at pre-agreed public seams" .-> TDD[tdd]

Invoke discover-opportunity when no problem or direction is known. It runs only on /discover-opportunity in Claude Code or $discover-opportunity in Codex. Start with shape-idea when the problem and a broad direction are already known. The discovery handoff remains in the conversation rather than a separate file.

shape-idea records implementation-ready decisions in docs/specs/<slug>/spec.md. build-prototype can start from the current conversation alone; when a whole interface is approved, it creates or updates the spec and preserves prototype.html beside it. Use split-into-tasks only when the spec contains outcomes that should be delivered separately. It also marks the few intermediate reviews justified by material or downstream risk. Then pass the spec folder to implement. It runs approved tasks sequentially when they exist and otherwise implements spec.md directly. After complete verification, the current harness's automated code-review process checks the integrated result against the selected spec and acceptance criteria. Implementation planning is just in time, and implement uses tdd where behavior can be verified through pre-agreed public seams.

Pass the folder itself, not an individual spec or task file.

Claude Code:

/implement docs/specs/checkout/

Codex:

$implement docs/specs/checkout/

The handoff lives at one stable path:

docs/specs/checkout/
├── spec.md
├── prototype.html      # optional
└── tasks/              # optional approved task files

Invoke the same folder again after an interruption. implement reconstructs progress from the folder, Git, the current diff, and verification results.

• discover-opportunity: Find side-project directions from agreed personal traces and relevant current change. Runs only when explicitly invoked and hands the chosen direction to shape-idea without creating a document.
• shape-idea: Clarify a chosen problem and direction through correctable drafts, project evidence, and rendered UI variants. Maintains project terms, records only settled decisions that future work should reuse, then writes an implementation-ready spec.
• build-prototype: Build every screen in one dummy-data HTML file using the project's design system, or the shell's minimal style when none exists. Review the rendered screens and preserve the approved prototype beside the spec.
• split-into-tasks: Split an existing spec into the fewest approved, independently deliverable vertical tasks with explicit blockers, acceptance criteria, focused verification, minimal state, and only risk-justified intermediate review checkpoints. Adapted from mattpocock/skills (MIT).
• implement: Implement an approved spec folder, using its tasks sequentially when present and its spec directly when absent, using tdd at pre-agreed public seams, then finish with full verification and the current harness's automated code-review process.
• tdd: Implement one red → green slice at a time at pre-agreed public seams. Includes rules for stable seams and behavioral tests. Adapted from mattpocock/skills (MIT).

Five standalone skills cover the repository handoff from a local change to a merged base branch. Invoke them directly with /commit, /pull, /push, /pr, or /merge in Claude Code and $commit, $pull, $push, $pr, or $merge in Codex.

When Codex exposes the managed plugin namespace, or a user-level skill with the same short name is also installed, use $toycrane-skills:commit, $toycrane-skills:pull, $toycrane-skills:push, $toycrane-skills:pr, or $toycrane-skills:merge to select this bundle unambiguously.

flowchart LR
    C["commit<br/>record in-scope changes"] --> P["push<br/>publish existing commits"]
    P --> PR["pr<br/>open ready-for-review PR"]
    PR --> M["merge<br/>verify merge and clean up"]
    L["pull<br/>rebase onto remote base"] -. "synchronize when needed" .-> C
    L -. "synchronize when needed" .-> P

Each skill is independently installable and owns its whole advertised outcome. push deliberately leaves dirty changes local. pr may perform the necessary commit, synchronization, and publication, but stops before merge. merge continues through verified remote merge and cleans up only resources owned by the merged worktree.

• commit: Record only the current request's changes as logical Conventional Commits while preserving unrelated work.
• pull: Rebase the current checkout onto the fetched requested base, or remote default, without treating a dirty tree as permission to modify local work.
• push: Publish existing commits on a named branch, reconciling remote state and using lease protection for intentional rewrites.
• pr: Turn the current change into a ready-for-review GitHub pull request and return its URL without merging it.
• merge: Carry a change through verified pull request merge, choose squash or rebase by commit meaning, then safely clean up the merged worktree and its owned development server.

Five additional skills run independently of the pipeline. They handle stack setup, project knowledge, visual explanation, final human judgment, and periodic cleanup.

• add-stack-context: Audit the technologies that define a project's stack and install each vendor's official agent context in its recommended form. Runs during agent setup, after stack changes, or on entering an unaudited project.
• project-knowledge: Maintain project terms and settled decisions that future work should reuse whenever they are taking shape, including while a plan weighs alternatives. Does not run for lookup, routine implementation details, or execution of settled decisions.
• explain-visually: Render explanations with the best available tool. Use one sentence instead when one sentence fully answers the question.
• human-review: Turn a completed, substantial or consequential repository change into a minimal visual handoff when the user asks to inspect actual outcomes and judge unresolved commitments. Show the whole outcome, then focus one review set on at most three active questions.
• compact-decisions: Periodically clean up decision files, the glossary, shipped specs, and agent instructions after work accumulates. Shorten the documents without changing confirmed decisions.

The skill-writing philosophy behind this project is deeply inspired by Matt Pocock's work—especially his approach to making stochastic systems more predictable through clear, compact, and checkable instructions. Thank you to Matt for articulating and openly sharing these ideas through mattpocock/skills.

MIT. See LICENSE.