push
toy-crane/skills · skills.sh
Open source Repository Open in the app JSON README (API)
About
Skill publicada por toy-crane/skills no skills.sh. Instale com: npx skills add toy-crane/skills@push
Details
- Kind
- Agent skills
- Publisher
- toy-crane
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 3
- Last push
- 2026-10-02T23:31:50Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-10-07 06:23:40
- Updated
- 2026-10-07 06:23:40
- Origin id
toy-crane/skills/push
README
# Skills
[](https://skills.sh/toy-crane/skills)
A composable, model-agnostic set of skills for product definition, shaping,
prototyping, task splitting, implementation, runtime verification, human
review, project knowledge, verified follow-up resolution, test-first
development, writing publications and pieces, project skill updates with
cross-client custom-agent synchronization, and safe Git delivery. Install selected skills or the complete plugin.
## Install
Choose copy-in installation or the managed plugin.
### skills.sh (copy into your project)
Copies selected skill folders into your project for local editing.
```bash
npx skills@latest add toy-crane/skills
```
Choose the skills and coding agents to install.
If an existing copy was installed before the source catalog moved into the
`git`, `workflow`, and `expo` groups, run the add command once more instead of
relying on `skills update`. The CLI tracks the exact upstream skill path, while
the reinstallation keeps the same skill names and refreshes that path.
`update-project-skills` reports such entries instead of reinstalling them.
The product-context workflow replaces `discover-opportunity` with
`define-product` and renames `compact-decisions` to
`maintain-project-context`. A copy-in installation does not receive aliases for
the retired names; remove those old copied folders after installing the
replacements.
### Project update (installed skills + companion agents)
Install `update-project-skills` once, then invoke it whenever a project should
follow the latest published skills:
```bash
npx -y skills@latest add toy-crane/skills \
--skill update-project-skills \
--agent codex claude-code \
-y
```
Use `/update-project-skills` in Claude Code or `$update-project-skills` in
Codex. It updates every skill recorded in `skills-lock.json` through
`skills update`, whatever its source, then reconciles the Toycrane set:
installs newly published skills that apply to the project's stack, retires
unpublished managed skills, and materializes any companion custom agents into
both `.claude/agents/` and `.codex/agents/`. Third-party skills are refreshed in
place only, and the locks preserve project-owned skills and agents unless the
user explicitly approves adopting a colliding name.
This is the cross-client installation path for companion agents. A skill folder
can carry their source payload, but neither client discovers that nested payload
as a native custom agent on its own.
### Claude Code plugin (managed bundle)
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:
```bash
claude plugin marketplace add toy-crane/skills
claude plugin install toycrane-skills@toycrane
```
The plugin installs the managed skill bundle for Claude Code. Run the
project-local sync workflow above when the same project also needs companion
agents in Claude Code and Codex.
## The pipeline
Six skills cover product definition through implementation.
```mermaid
flowchart LR
DP["define-product<br/>(rough direction known)"] --> READY{"whole direction clear<br/>without guessing?"}
READY -- "no" --> ASK["ask about real use<br/>(no guessed answers)"]
ASK --> READY
READY -- "yes" --> REQUEST{"writing already<br/>requested?"}
REQUEST -- "yes" --> PRODUCT[/PRODUCT.md/]
REQUEST -- "no" --> DRAFT["show the whole direction"]
DRAFT --> CONFIRM{"confirmed?"}
CONFIRM -- "not yet" --> ASK
CONFIRM -- "yes" --> PRODUCT
PRODUCT -. "read when present" .-> SI["shape-idea<br/>(one work unit)"]
SI --> BP["build-prototype<br/>(judge it by using it)"]
SI --> SPEC[/spec folder/]
BP --> SPEC
SPEC --> ST["split-into-tasks<br/>(shallow outcome map)"]
SPEC --> IM["implement<br/>(spec folder)"]
ST --> IM
IM --> ONE["build one outcome"]
ONE --> CHECK["check real behavior"]
CHECK --> MATCH{"still matches the spec<br/>and remaining tasks?"}
MATCH -- "technical facts changed" --> UPDATE["update active tasks"]
UPDATE --> ONE
MATCH -- "work-unit promise changed" --> SI
MATCH -- "app premise changed" --> DP
MATCH -- "yes" --> MORE{"more outcomes?"}
MORE -- "yes" --> ONE
MORE -- "no" --> FULL["full deterministic checks"]
FULL --> REVIEW["complete one code review"]
REVIEW -- "result for intended diff" --> TRIAGE{"breaks a criterion or<br/>reproduces as a defect?"}
REVIEW -- "no completed result" --> PENDING["review pending<br/>share verified result + blocker"]
PENDING -- "failure resolved or authority granted" --> REVIEW
PENDING -- "explicit user waiver" --> FINAL
TRIAGE -- "yes" --> FIX["repair, recheck<br/>(no second review)"]
FIX --> FINAL["final changed/core loop<br/>on every claimed platform"]
TRIAGE -- "no" --> REC["record: follow-up,<br/>note, or user decision"]
REC --> FINAL
FINAL -- "in-scope defect" --> FIX
FINAL -- "blocked" --> BLOCKED["runtime pending<br/>share evidence + prerequisite"]
BLOCKED -- "prerequisite restored" --> FINAL
FINAL -- "passes" --> DONE["verified and runnable<br/>reviewed or explicitly waived"]
IM -. "uses at public seams" .-> TDD[tdd]
IM -. "proves affected surfaces" .-> RV["matching runtime skill<br/>or strongest usable path"]
IM -. "open workaround or<br/>out-of-scope defect" .-> FU["follow-up"]
```
Invoke `define-product` when starting a from-scratch app whose rough direction
or problem is already known. It starts from a concrete use scene and draws out
the user's product meaning instead of filling gaps from the initial solution
idea. After the complete direction is confirmed, it creates or revises root
`PRODUCT.md` with the users and situations, problem and alternatives, promised
change, core loop, capabilities and boundaries, experience principles, success
signals, assumptions, and unknowns. Blank-page idea discovery is outside this
workflow.
Start with `shape-idea` when one concrete problem and broad work-unit direction
are already known. It reads `PRODUCT.md` when present but remains independently
usable when the file is absent, and it neither creates nor edits app-level
product context.
`shape-idea` records one stable product contract in
`docs/specs/<slug>/spec.md`: user-visible outcomes, scope, observable acceptance
criteria, settled constraints and rationale, assumptions, off-limits areas and
reasons, deferrals, and risks. `build-prototype` can start from the current
conversation alone; when a whole interface is approved and consequential
non-visual behavior is settled or explicitly deferred, it creates or updates
that same contract and preserves `prototype.html` beside it. Use
`split-into-tasks` only
when the spec contains outcomes that should be delivered separately. It also
creates the complete shallow outcome map without predicting files, functions,
code structure, or a step-by-step implementation sequence. It marks only the
few intermediate reviews justified by material or downstream risk.
Then pass the spec folder to `implement`. Before each outcome, it reloads the
current spec, active unfinished tasks, and any completed or superseded task
implicated by current evidence, plus code, Git state, and verification evidence,
then plans only that outcome in detail. After focused verification, it checks
the observed result against the product contract and every active unfinished
task. It may update technical assumptions and affected active tasks when the
approved product behavior stays the same. If an approved outcome, observable
acceptance criterion, scope, or other product constraint must change, it stops
and returns that exact decision to shaping. A task marked `completed` is
reopened if later evidence shows its criteria no longer pass. When an approved
breakdown replaces historically completed work, its still-required obligations
move to the replacement; the old task remains only as inactive `superseded`
evidence and cannot block or re-enter the delivery frontier.
After every outcome passes that check, the current harness's automated
code-review process reads the integrated result once against the selected spec
and acceptance criteria. `implement` picks the depth that change warrants, and
its findings are triaged rather than looped: `implement` repairs only what
breaks an approved acceptance criterion or reproduces as a defect on an
ordinary path, then records the rest as follow-ups, disposed trade-offs, or
decisions the user owns. Completion requires a finished review of the intended
diff or an explicit user waiver; it does not require zero findings. Failed,
partial, silent, or mistargeted attempts do not count as the one pass.
`implement` recovers execution errors within the authorized scope and retries.
It accurately identifies any model service and source context, reuses existing
user authorization without asking again, and requests only missing authority.
An explicit policy denial requires a permitted safer path or the needed
authority before retrying. If review cannot finish, overall completion stays
pending while verified outcomes, the blocker, and the next action are provided.
When the repository exposes the result through a
user-reviewable local server, `implement` verifies the changed surface and
shares an address while leaving that server available until the user finishes
review or later delivery cleanup. `implement` uses `tdd` where behavior can be
verified through public seams it selects from the agreed behavior and existing
interfaces. For an affected product surface, it
uses an available matching runtime-verification skill. When none is available,
it autonomously investigates the repository and current environment and builds
the strongest usable runtime path instead of asking the user to approve the
method. After focused checks and reconciliation, it runs the complete
deterministic checks, then the whole-diff review and any must-fix repairs with
affected verification. It finally verifies the changed flow and the
`PRODUCT.md` core loop on every claimed platform, including when review is
explicitly waived; missing core-loop coverage is reported rather than invented.
An in-scope defect found at that final gate returns to repair, affected checks,
and final verification of the repaired revision without a second review.
Current-scope gaps stay in implementation. A workaround with an open root cause
or an evidenced out-of-scope defect becomes a durable follow-up.
Pass the folder itself, not an individual spec or task file.
Claude Code:
```text
/implement docs/specs/checkout/
```
Codex:
```text
$implement docs/specs/checkout/
```
The handoff lives at one stable path:
```text
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; a
new session or a closing-message handoff is not required for correctness.
- **[define-product](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/define-product/SKILL.md)**: Draw out the
product meaning behind a rough app direction, confirm it with the user, and
preserve it in one current root `PRODUCT.md`. Keep app-level users, problem,
promise, core loop, boundaries, experience principles, success signals,
assumptions, and unknowns available across later work units without
absorbing technical or feature-level detail.
- **[shape-idea](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/shape-idea/SKILL.md)**: Clarify a chosen problem and
direction through correctable drafts, project evidence, and rendered UI
variants. Maintain project terms and write the stable product contract that
later task splitting and implementation must preserve.
- **[build-prototype](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/build-prototype/SKILL.md)**: 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 same product contract used by shaping.
- **[split-into-tasks](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/split-into-tasks/SKILL.md)**: Split an existing
spec into the complete shallow map of the fewest approved, independently
deliverable vertical tasks, without predicting code-level implementation.
Include explicit blockers, acceptance criteria, focused verification, minimal
state, and only risk-justified intermediate review checkpoints, each one
bounded review pass.
Adapted from [mattpocock/skills](https://github.com/mattpocock/skills) (MIT).
- **[babysit-specs](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/babysit-specs/SKILL.md)**: Bring queued spec
folders back in line with what shipped since their last commit. Fix the
staleness that preserves the approved meaning as an overridable assumption,
ask one question about each point that would change it, and hand affected
tasks, drifted prototypes, and retirement candidates to their owners without
editing product source.
- **[implement](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/implement/SKILL.md)**: Implement an approved spec
folder one outcome at a time. Reload repository evidence before each outcome,
reconcile verified behavior with the product contract and active unfinished
tasks, ignore superseded history unless current evidence implicates it, reopen
invalidated work, and return to shaping when a product decision must change.
Then finish with full verification and one completed, triaged automated
review, unless explicitly waived by the user. Recover review execution
failures and reuse granted authority; blocked review leaves completion pending
while the verified result and runnable product address remain available.
- **[tdd](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/tdd/SKILL.md)**: Select public test seams from the agreed
behavior and existing interfaces, then implement one red → green slice at a
time. Includes rules for stable seams and behavioral tests.
Adapted from
[mattpocock/skills](https://github.com/mattpocock/skills) (MIT).
## The writing pipeline
Three skills carry the same premise → brief → draft structure over to prose,
for a publication that lives in the same repository as its code, such as a
product blog inside a monorepo. They share `GLOSSARY.md`,
`docs/decisions/README.md`, and `project-knowledge` with the code pipeline, so
a piece about the product uses the product's own terms.
```mermaid
flowchart LR
DPUB["define-publication<br/>(one medium)"] --> PUB[/"docs/publications/<slug>.md"/]
PUB -. "read when briefing" .-> DPI["define-piece<br/>(one topic)"]
DPI --> BRIEF[/"docs/briefs/<slug>/brief.md"/]
BRIEF --> DR["draft-piece<br/>(brief folder)"]
DR --> SEC["write one section,<br/>run its code"]
SEC --> CHANGE{"thesis, reader, or<br/>scope must change?"}
CHANGE -- "yes" --> DPI
CHANGE -- "no" --> MORE{"more sections?"}
MORE -- "yes" --> SEC
MORE -- "no" --> CHECK["reader questions by a<br/>fresh-context agent<br/>+ every marked command runs"]
CHECK --> FIX["revise once:<br/>failed questions and facts only"]
FIX --> HAND["draft at the content location<br/>+ local preview"]
HAND -. "after the user reads" .-> GIT["commit / pr"]
```
Skill bodies are medium-neutral. Everything that differs by medium, such as
form, length, where finished pieces live, how they are previewed, and what
evidences a finished piece, lives in the publication file, so a newsletter or
brand site later adds a file rather than a skill.
- **[define-publication](https://github.com/toy-crane/skills/blob/HEAD/skills/writing/define-publication/SKILL.md)**: Interview
the user about one medium's readers, promised change, voice, coverage,
conventions, and evidence, then preserve the confirmed premise in
`docs/publications/<slug>.md`, one file per medium. Recommend voice with a
short sample paragraph and retain the accepted example.
- **[define-piece](https://github.com/toy-crane/skills/blob/HEAD/skills/writing/define-piece/SKILL.md)**: Turn one topic into a
confirmed brief through correctable candidates: thesis, titles, outline,
three to five checkable reader questions, scope, material, and which code is
execution-checked. Reuse confirmed writing criteria and preserve feedback as
it is settled. Writes no body prose into the brief.
- **[draft-piece](https://github.com/toy-crane/skills/blob/HEAD/skills/writing/draft-piece/SKILL.md)**: Write the piece from its
brief folder section by section, running embedded code as it is written.
Verify with a fresh-context agent answering the reader questions and with
every marked command, and compare confirmed writing criteria. Use one bounded
automatic revision, preview locally, and stop before commit. Later user
corrections, including edits to an article without a brief, preserve scoped
reusable feedback in the repository for either Claude or Codex to read.
Claude Code:
```text
/draft-piece docs/briefs/monorepo-move/
```
Codex:
```text
$draft-piece docs/briefs/monorepo-move/
```
## Git delivery
Five standalone skills cover the repository handoff from a local change to a
merged base branch, and a sixth clears the worktrees that pile up afterward.
Invoke them directly with `/commit`, `/pull`, `/push`, `/pr`, `/merge`, or
`/clean-worktrees` in Claude Code and `$commit`, `$pull`, `$push`, `$pr`,
`$merge`, or `$clean-worktrees` 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`,
`$toycrane-skills:merge`, or `$toycrane-skills:clean-worktrees` to select this
bundle unambiguously.
```mermaid
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 the merged worktree,
releasing its resources through the project's declared cleanup commands.
- **[commit](https://github.com/toy-crane/skills/blob/HEAD/skills/git/commit/SKILL.md)**: Record only the current request's
changes as logical Conventional Commits while preserving unrelated work.
- **[pull](https://github.com/toy-crane/skills/blob/HEAD/skills/git/pull/SKILL.md)**: Rebase the current checkout onto the fetched
requested base, or remote default, without treating a dirty tree as permission
to modify local work.
- **[push](https://github.com/toy-crane/skills/blob/HEAD/skills/git/push/SKILL.md)**: Publish existing commits on a named branch,
reconciling remote state and using lease protection for intentional rewrites.
- **[pr](https://github.com/toy-crane/skills/blob/HEAD/skills/git/pr/SKILL.md)**: Turn the current change into a ready-for-review
GitHub pull request with a proportionate behavior explanation, verification
evidence, and attached before-and-after screen comparisons when applicable;
return its URL without merging it. With an issue tracker configured, first
create the issue for each carried spec folder that has no `Issue:` line and
commit that line.
- **[merge](https://github.com/toy-crane/skills/blob/HEAD/skills/git/merge/SKILL.md)**: Carry a change through verified pull
request merge with the same self-contained body and visual-evidence guidance,
choose squash or rebase by commit meaning, then safely clean up the merged
worktree with the project's declared cleanup commands.
- **[clean-worktrees](https://github.com/toy-crane/skills/blob/HEAD/skills/git/clean-worktrees/SKILL.md)**: Sweep a
repository's accumulated worktrees in one pass. Remove those whose pull
request merged or closed, detached ones the base already contains, and
left-over folders that lost their Git registration; report open,
uncommitted, session-attached, and Codex-managed ones with the reason they
stayed.
A project that gives each worktree its own servers, devices, or databases
declares how to release them in `AGENTS.md` or `CLAUDE.md`. `merge` and
`clean-worktrees` run the commands in order inside a worktree before removing
it. Without the section they stop no process, and they leave a worktree that
another session or terminal still uses.
````md
## Worktree cleanup
Release this worktree's development resources. Agents run these from the worktree root.
```sh
bun run dev:remove
bun run db:remove
```
````
## Supporting workflows
Ten additional skills can run independently. They handle stack setup, issue
tracker coordination for parallel spec work, Expo runtime verification,
pre-delivery both-platform checks, cross-client skill and agent
synchronization, incremental project knowledge, verified follow-up resolution,
visual explanation, final human judgment, and periodic context maintenance.
`implement` also uses a matching runtime-verification skill when one is
available for an affected product surface.
- **[add-stack-context](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/add-stack-context/SKILL.md)**: Audit the
technologies that define a project's stack, discover vendor-controlled skills,
keep changing official guidance live, and surface community skills for
approval. Runs during agent setup, after stack changes, or on entering an
unaudited project.
- **[setup-issue-tracker](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/setup-issue-tracker/SKILL.md)**: Record
once per repository which issue tracker coordinates spec folders and, when
requested, general-issue triage. Each spec folder names its one issue with an
`Issue:` line: the PR that first carries the folder creates the issue, and a
spec that starts from an existing issue records that one. Every lookup uses
the recorded ID. `implement` claims the issue, and context maintenance repairs
drift. Without the convention every skill behaves as before.
- **[triage-issues](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/triage-issues/SKILL.md)**: On a schedule or
by hand, handle one named issue or up to three new human-written issues no
earlier run triaged, including Backlog, each once.
Investigate and raise one verified implementation or spec PR when ready, or
ask for only the missing information or product decision with evidence.
Preserve the original issue throughout and prevent competing runs from
handling it together through an atomic remote claim.
- **[expo-dev-loop](https://github.com/toy-crane/skills/blob/HEAD/skills/expo/expo-dev-loop/SKILL.md)**: Verify Expo and React
Native changes in a running app with `agent-device`, first proving target
readiness and the scenario's required state, then selecting Metro reload or
native rebuild and completing only with device evidence.
- **[expo-smoke-test](https://github.com/toy-crane/skills/blob/HEAD/skills/expo/expo-smoke-test/SKILL.md)**: Before delivery,
prepare a known-app, fresh-device, or preserved-prior state as the scenario
requires, then drive the current change and the `PRODUCT.md` core loop on iOS
and Android development builds through one isolated `expo-smoke-runner` per
platform.
- **[update-project-skills](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/update-project-skills/SKILL.md)**:
Update every skill installed in the project to its latest published version
with `skills.sh`, reconcile the Toycrane set, and install, refresh, or retire
its project-local companion agents for both Claude Code and Codex without
taking ownership of unrelated artifacts.
- **[project-knowledge](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/project-knowledge/SKILL.md)**: Maintain project
terms and settled decisions that future work should reuse whenever they are
taking shape, including while a plan weighs alternatives. Keeps root
`DESIGN.md`, the entry point for design work, mapped to the contracts that
own each on-screen element. Does not run for lookup, routine implementation
details, or execution of settled decisions.
- **[resolve-follow-ups](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/resolve-follow-ups/SKILL.md)**: Sweep
evidence-backed `docs/follow-ups/` items in bounded batches, reproduce each
symptom before editing, and publish verified fixes as independent
worktree-isolated pull requests without automatic merge.
- **[explain-visually](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/explain-visually/SKILL.md)**: Render explanations
with the best available tool. Use one sentence instead when one sentence fully
answers the question.
- **[human-review](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/human-review/SKILL.md)**: Help a human understand
AI-authored work through before-and-after behavior and nearby evidence. Keep
the whole change available to inspect, surface unsettled choices, and leave
a clear place to resume after switching tasks.
- **[maintain-project-context](https://github.com/toy-crane/skills/blob/HEAD/skills/workflow/maintain-project-context/SKILL.md)**:
Periodically reconcile `PRODUCT.md`, the glossary, decision contracts, shipped
specs, agent instructions, and any configured spec issues after work
accumulates. Apply only meaning that is already settled, refresh each spec
issue found by its `Issue:` line from the remote default branch, and leave
ambiguous conflicts for
explicit clarification.
## Output styles
- **[natural-korean](https://github.com/toy-crane/skills/blob/HEAD/output-styles/natural-korean.md)**: A Claude Code
response style for natural, spoken-register Korean instead of
translated-sounding Korean. Ships with the Claude Code plugin only —
skills.sh copies skill folders, not output styles. Select it with
`/output-style` after installing the plugin.
## Acknowledgements
The skill-writing philosophy behind this project is deeply inspired by
[Matt Pocock](https://github.com/mattpocock)'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](https://github.com/mattpocock/skills).
## License
MIT. See [LICENSE](https://github.com/toy-crane/skills/blob/HEAD/LICENSE).