Petalas Skills

Public agent skills distributed from GitHub and maintained with a small local plugin workflow.

This repo is designed for two jobs:

• installable skill source for the skills CLI
• local development home for plugin metadata, prompts, and supporting docs

If you only want to install a skill, use the commands below and ignore the internal layout.

Available Skills

Skill	What it does
adversarial-review	Run independent read-only reviewers and apply lead judgment to their findings.
architect	Design non-trivial code from usage and module boundaries before implementation.
arena	Generate, judge, and synthesize independent candidates for one artifact.
auditable-run	Design and execute an evidence-driven local workflow for a large task when no focused playbook fits.
automate-me	Create or update a personal mode skill from the user's stated preferences and workspace-scoped conversation history.
benchmark-checklist	Vet a perf measurement (limiter, tuning, limits, errors, repeatability, relevance, and whether the work happened) before you report or act on it. U...
blast-radius	Find breakage outside a diff and prove its load-bearing safety facts.
bro	Restate the last message in plain human language, with no jargon.
commit-guidelines	Conventional commits without AI co-author attribution
configure-agent-models	Record host-neutral model preferences for internal agent roles using only models available in the current environment.
correct	Find the mistakes agents keep repeating in this repo and make each one impossible. Try architecture first, then types, then a lint whose error name...
create-verification-skill	Create a project-local skill that drives an app through its real user surface and captures proof.
engineering-mode	Use when starting a software task that needs rigor: a bug, feature, refactor, investigation, performance issue, or any multi-step change to code th...
explain-code	Explain code by combining how it works with evidence for why it has that shape.
gpt-image-2-5	Subscription image generation with saved prompts and artifact inspection
how	Explain how code works: subsystem architecture, runtime flow, ownership, placement, and layering. Use why for historical motivation.
in-your-own-words	Restate in your own words what you think the user's goals are and what problem they're trying to solve.
ketchup	Catch the user up on what changed in this chat since their last message, in a few plain sentences and small visuals. Give each action item just eno...
knowledge-audit	Audit one project's knowledge system on request: check for a routing table that maps file patterns to docs, a When You Struggle capture process, an...
knowledge-migrate-all	Scan a chosen directory tree for projects with agent instructions files, run the knowledge-audit quick check on each, and report which are current,...
maintain-verification-skill	Audit a project verification skill against source and every mapped user-facing feature, then apply proven local corrections.
power-of-ten	Apply when writing or changing code that will be committed, tested, or run more than once. Hold every touched path to the ten language-agnostic rul...
principle-attack-the-premise	Apply when two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before you write another...
principle-boundary-discipline	Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs);...
principle-build-the-lever	Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, ...
principle-encode-lessons-in-structure	Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata fla...
principle-exhaust-the-design-space	Apply when facing a novel UI interaction or architectural decision with no precedent in the codebase. Build 2-3 competing prototypes and compare si...
principle-experience-first	Apply when product, UX, or feature-scope tradeoffs come up. Choose user delight over implementation convenience; ship fewer polished features over ...
principle-explain-the-number	Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what lim...
principle-fix-root-causes	Apply when debugging. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it ha...
principle-foundational-thinking	Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get ...
principle-guard-the-context-window	Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main ...
principle-laziness-protocol	Apply when refactoring, evaluating diff size, or tempted to add abstractions, layers, or signal threading. Bias toward deletion and the smallest ch...
principle-local-autonomy	Apply when reversible local work can proceed without a permission pause. Keep agents autonomous inside the workspace while reserving external commu...
principle-make-operations-idempotent	Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state re...
principle-minimize-reader-load	Apply when reviewing or shaping code that's hard to trace. Count layers between question and answer, and hidden state in the reader's head; collaps...
principle-model-domain-in-code	Apply when writing stateful logic, or when code branches a lot or repeats a shape assumption across files. Encode the domain in a structure instead...
principle-outcome-oriented-execution	Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediat...
principle-prove-it-works	Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), ...
principle-redesign-from-first-principles	Apply when integrating a new requirement into an existing design. Redesign as if the requirement had been a foundational assumption from day one, i...
principle-replace-internal-apis-atomically	Apply when introducing a new internal API while old callers still exist. Migrate callers and delete the old API in the same wave instead of preserv...
principle-separate-before-serializing-shared-state	Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only w...
principle-sequence-verifiable-units	Apply to multi-step work such as sweeps, migrations, and runs of similar edits. Break work into small units that each end in a verifiable state, ch...
principle-subtract-before-you-add	Apply when sequencing an addition, refactor, or rewrite. Remove dead code, redundant validators, and stub references first, then build on the simpl...
principle-test-behavior-not-implementation	Apply when you write, change, or keep a test. Assert what the code's users can observe, so that the test fails when that behavior breaks and keeps ...
principle-type-system-discipline	Apply when designing types, reviewing a function signature, or writing code in any statically-typed language. Make illegal states unrepresentable, ...
recall	Reconstruct recent solo-development context and return a concise current-state brief.
reflect	Review the active session through independent lenses and propose durable skill improvements for user approval.
regression-test	Use when the user asks for a regression test, or when a bug has an obvious cheap local test seam. Do not use for general TDD or test-first feature ...
review-code-comments	Review source-code comments and apply only authorized local cleanups.
safe-refactor	High-value safe refactors with evidence first
sharpen	Sharpen a task before starting: the expert approach, what the user is really after, and the right level of specification.
show-me-your-work	Keep a local, reviewable TSV decision trail for long-running, unattended, or multi-phase work.
swarm	Fan out subagents, drain every required result, and consolidate the report.
technical-writing	Layered technical-writing standard: Diataxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for $te...
typescript-best-practices	TypeScript best practices. Use when reading or editing any TypeScript or JavaScript file (.ts, .tsx, .js, .mjs, .cjs).
unslop	Cut AI tells from any writing. Use when writing or editing prose a person will read.
why	Investigate why code has its current shape from read-only evidence.
worktree-cleanup	Audit git worktrees and local development caches, then remove only targets proven unused and recoverable.

See the full catalog for categories and installation.

Start with the solo developer workflow guide for a host-neutral path through understanding, design, implementation, verification, and long-running local work.

The generated catalog links every plugin README, including its prompts, workflow details, and source paths.

Install

List skills in this repo:

bunx skills@latest add petalas/skills --list

Install commit-guidelines globally:

bunx skills@latest add petalas/skills --skill commit-guidelines -g -y

Install safe-refactor globally:

bunx skills@latest add petalas/skills --skill safe-refactor -g -y

Install the optional solo-development router globally:

bunx skills@latest add petalas/skills --skill engineering-mode -g -y

Install commit-guidelines for the current project:

bunx skills@latest add petalas/skills --skill commit-guidelines -y

Update

Once installed from petalas/skills, refresh installed skills with:

bunx skills update

How updates actually work

The upstream skills CLI is source-driven, not package-version-driven:

• global installs check the remote GitHub skill-folder hash and update when that folder changes
• project installs refresh from the original source when bunx skills update runs
• any file inside the installed skill folder can matter, not just SKILL.md

That means publishing a new version of a skill is usually just:

1. change the repo
2. commit and push to main
3. users run bunx skills update

The plugin version in .codex-plugin/plugin.json is still useful release metadata for humans, but it is not the primary update signal used by the CLI.

Repository Layout

This repo keeps public install support and internal plugin metadata in the same tree:

plugins/<name>/
  .codex-plugin/plugin.json
  README.md
  commands/<name>.md
  skills/<name>/
    SKILL.md
    agents/openai.yaml
    references/*                 # when needed
    THIRD_PARTY_NOTICES.md       # pstack-derived skills
.agents/plugins/marketplace.json
docs/PLUGIN_CATALOG.md

What each layer is for:

• SKILL.md contains the actual skill instructions
• commands/ provides command entrypoints like $commit-guidelines and $safe-refactor
• .codex-plugin/plugin.json stores plugin metadata and public-facing display information
• .agents/plugins/marketplace.json supports local plugin development
• plugin-level README.md files make the repo easier to browse without digging through prompt files
• THIRD_PARTY_NOTICES.md travels with individually installed derived skills

Public installs still work from the GitHub repo root even though the skill lives inside a plugin-oriented structure.

Development

bun install
bun run hooks:install
bun run format
bun run format:check

Quality checks:

• local pre-commit hook runs bun run format:check
• GitHub Actions runs bun run check on pull requests and pushes to main
• Prettier is the single formatter for this repo, including Markdown, YAML, JSON, and config files

More detail:

• contribution workflow: CONTRIBUTING.md
• release and update process: docs/RELEASING.md
• repository gotchas: LEARNINGS.md

Philosophy

• keep public installation simple
• keep skills concrete and high-signal
• prefer repo-documented workflows over agent-specific guesses
• allow internal agent coordination without agent-to-human communication
• make maintenance boring: formatters, hooks, CI, and release notes should do the repetitive work

The pstack-derived collection follows the solo agent policy. Agents may work together, but the user handles communication with other people.

Pstack provenance

The derived collection uses pstack 0.15.25 at commit 101b274dd991f694e1f7024be2157e5f3adf07de as its fixed upstream baseline. See the 0.15.25 port decisions for changes and exclusions. Each substantially copied or adapted skill contains Lauren Tan's full MIT notice and an exact source-path table inside its installed directory. See the import manifest and the component inventory. Follow Update skills from pstack to compare a newer upstream commit, classify every changed path, update mappings, and verify the port.