Skillz

Production software skills for Claude Code, Codex, Cursor, Mission Control, and other Agent Skills runtimes.

Jstack is this repository's governed, cross-harness distribution of the planning, implementation, review, and engineering-principle skills imported from the credited upstream sources.

Jstack is derived from Cursor's pstack plugin, created by Lauren Tan and released under the MIT license. This repository is a cross-runtime port. The Jstack name identifies this repository's integration and safety work. It does not replace pstack's authorship.

The collection also includes a reviewed, pinned import of 24 skills from BuilderIO/skills. They cover agent review, model orchestration, Agent-Native apps, visual planning and editing, WebMCP, and experimental software-factory workflows.

The collection also adapts seven production engineering skills from addyosmani/agent-skills, covering API contracts, CI/CD, migrations, UI quality, observability, performance, and security. The selection review accounts for all 25 upstream skills and explains the corrections and overlap decisions.

Five focused workflows from davidondrej/skills add session handoffs, decision records, product assumption checks, read-only database access planning, and verified instructions for teammates. The selection review accounts for all 62 upstream skills.

This repository packages 108 skills behind one canonical skills/ tree:

• 8 core delivery, architecture, evidence, review, and writing skills
• 40 Jstack workflows for planning, implementation, review, and operations
• 24 Jstack engineering principles
• 24 Builder.io and Agent-Native workflows
• 7 adapted Addy Osmani production engineering workflows
• 5 adapted David Ondrej continuity, decision, and access workflows

Every skill uses portable Agent Skills frontmatter. Claude Code, Codex, Cursor, and custom runtimes read the same SKILL.md bodies. Runtime metadata and plugin manifests stay beside the canonical tree. Mission Control governance metadata stays inside the standard metadata map.

This is a mixed-source collection. Read Licensing and attribution before redistributing an individual skill.

The October 25 upstream review records the seven checked source repositories, current revisions, all 11 new Jstack skills, retained local fixes, and deferred original-source additions. Source hashes and license receipts are in vendor/upstream-review.json.

New in 2.6.0

These are standalone adaptations with pinned provenance and complete MIT notices. The database workflow requires explicitly approved access and keeps row-level security. The import adds no external services or executable helpers. Codex keeps explicit invocation for handoff, create-readonly-db-role, and prompt-for-others; the other two use normal task-based discovery.

Added in 2.5.0

before-and-after now formats existing media and uses GitHub attachments. Capture stays with the host's browser tools. Check for --attach in the installed gh help before publishing. Local formatting works without it.

The refresh also fixes recorder startup when Linux refuses pidfds, preserves unrelated PR text when replacing visual evidence, and packages all four companion agents for plugin and portable installs. The original Cursor statechart and ketchup-video additions remain deferred. Their integration decisions are in the source review.

Why this repository exists

Agent workflows become unreliable when each harness has a different copy, skills silently overwrite one another, or an orchestration prompt is mistaken for permission to publish, merge, deploy, or spend money.

Skillz provides:

• one source of truth for Claude Code, Codex, Cursor, and custom runtimes
• explicit activation descriptions instead of loading every skill into context
• a tested package-wide routing budget so all skill descriptions remain discoverable
• a Mission Control delivery contract from mission to release evidence
• a pinned, reproducible distribution with upstream attribution
• tightened authority boundaries for external writes and product decisions
• conflict-safe user and project installers
• package, link, manifest, installer, and workflow tests

Start here

For non-trivial software-factory work:

1. Load mission-control-delivery when Mission Control or another governed execution system owns the work.
2. Use poteto-mode to select the smallest applicable workflow.
3. Load only the specialist skills that match the task.
4. Verify the exact candidate before declaring the work complete.
5. Treat publication, merge, deployment, destructive cleanup, external communication, and spending as separate authority boundaries.

Do not preload all 108 skills. Descriptions are the routing layer; the selected SKILL.md files are the execution layer.

Choose an installation

Mission Control is optional. It is one consumer of this repository, not a requirement for Claude Code, Codex, Cursor, or another runtime.

Install with the repository installer

git clone https://github.com/jaydubya818/skillz.git
cd skillz

# Always inspect the user-level change first.
python3 scripts/install_skills.py --all --dry-run

# Install for Claude Code, Codex, and Cursor.
python3 scripts/install_skills.py --all

If a destination already contains a different skill with the same name, the installer stops before writing anything. Review the conflict, then explicitly choose replacement if the collection should win:

python3 scripts/install_skills.py --all --replace

Replacement moves the old directory to <skill>.backup, then .backup-2, and so on. An already-current copy is skipped, making repeated installs idempotent.

Upgrade an existing installation

From a clean checkout on main, update the source and preview replacement of your installed copies:

git pull --ff-only origin main
python3 scripts/install_skills.py --all --replace --dry-run

Review the destinations and backups, then apply the update:

python3 scripts/install_skills.py --all --replace

Use --claude, --codex, or --cursor instead of --all to update one runtime. For a project installation, add --project /path/to/project to both installer commands. Copy installs need the installer rerun. Existing symlinked skills follow changes in the checkout, provided it stays at the same path. Rerun the installer to add new skills or companion agents to either install type.

Merging repository changes does not update installed copies or publish a release. Tagged source archives are published only by the separate v* release workflow.

Runtime-specific installation

User-level Claude Code installation

python3 scripts/install_skills.py --claude --dry-run
python3 scripts/install_skills.py --claude

Destination: ~/.claude/skills/

Claude Code can also load a checkout directly while developing the plugin:

claude --plugin-dir /path/to/skillz

The Claude plugin manifest is .claude-plugin/plugin.json.

To install the public Claude plugin from inside Claude Code, add this repository as a marketplace and install its package:

/plugin marketplace add jaydubya818/skillz
/plugin install software-factory-skills@skillz

User-level Codex installation

python3 scripts/install_skills.py --codex --dry-run
python3 scripts/install_skills.py --codex

Destination: ~/.agents/skills/, the user-level location documented by OpenAI's skill guide.

Each skill includes agents/openai.yaml for its Codex display name, concise description, and explicit invocation prompt. The collection manifest is .codex-plugin/plugin.json.

The root plugin.json follows the Agent Plugins standard. It packages the same tree for products that support that format.

User-level Cursor installation

python3 scripts/install_skills.py --cursor --dry-run
python3 scripts/install_skills.py --cursor

Destination: ~/.cursor/skills/. Cursor syncs personal skills from this path to Cursor Cloud Agents. The repository also includes .cursor-plugin/plugin.json for local plugin testing and marketplace submission.

Custom runtime installation

Pass the runtime's skill directory as an exact destination:

python3 scripts/install_skills.py \
  --portable /path/to/runtime/skills \
  --dry-run

python3 scripts/install_skills.py \
  --portable /path/to/runtime/skills

This mode installs only the canonical skills. A custom runtime must map its tools and worker controls with the harness-tools.md guide.

Optional Agent-Native connections

The repository installer copies skill instructions only. It does not install desktop software, authenticate accounts, or edit a runtime's MCP settings. Plugin-capable Claude and Codex installs can read the bundled .mcp.json, which declares only the Agent-Native Dispatch server. The runtime still controls connection approval, authentication, and app grants.

When a companion capability is missing, these skills stop with setup guidance; they do not silently install software, bypass authentication, or substitute an unapproved external service. Cursor and custom harness users must configure the required connectors through their runtime's documented MCP settings.

Project-scoped installation

Copy the skills into the shared runtime directories for one project:

python3 scripts/install_skills.py \
  --all \
  --project /path/to/project

Or keep this checkout as the canonical source and create links:

python3 scripts/install_skills.py \
  --all \
  --mode symlink \
  --project /path/to/project

Project installs target .claude/skills/ for Claude Code. Codex and Cursor share .agents/skills/, so --all writes that tree once. Claude installs also place the four companion agents in .claude/agents/. Copy mode is portable. Symlink mode lets an active checkout feed each runtime without duplicate edits.

Mission Control integration

mission-control-delivery maps agent work onto this lineage:

Mission
└── WorkOrder
    └── Task
        └── Attempt
            ├── decisions and run log
            ├── evidence tied to an exact candidate
            ├── pull request or reviewed artifact
            └── release handoff

The skill is a reasoning and handoff contract. It does not grant permission to claim work, change Mission Control state, publish a context package, merge a pull request, deploy a release, or spend money. API-specific Mission Control skills and the active approval policy remain authoritative for those actions.

For Mission Control builds with the portable Agent Skills compatibility layer, the local scanner checks these roots in deterministic order:

1. skills/
2. .agents/skills/
3. .claude/skills/
4. .codex/skills/ (legacy compatibility)
5. .cursor/skills/

Identical same-name installations collapse to one skill. Different definitions with the same name stop discovery and report both paths. Repository discovery does not publish, activate, or grant authority by itself.

The recommended standing repository policy is:

For non-trivial work, start with mission-control-delivery. Then use
poteto-mode to select a workflow and load only the applicable specialist
skills. System, user, Mission Control, and repository instructions override
skill guidance. External writes require explicit task authority.

Recommended routes

Complete skill catalog

Risk is a routing and review hint, not permission. A low-risk skill can still propose an action that requires approval in the current task.

Core collection: 8 skills

Builder.io agent and orchestration workflows

Builder.io Agent-Native workflows

Builder.io experimental Factory workflows

Factory modules share the configuration guide bundled under skills/factory/references/. Start with manual or read-only operation. Fixes, replies, publication, approval, merge, deployment, recovery, and notifications remain separate gates.

Jstack planning, architecture, and understanding

Jstack implementation and quality

Jstack parallel work and adversarial review

Jstack pull-request and delivery workflows

Jstack context and operating workflows

Jstack engineering principles: 23 skills

These are focused reasoning aids. They should be loaded when the situation matches, not injected into every task.

Addy Osmani production engineering skills

These are curated adaptations, not an installation of the upstream plugin. Each is self-contained, carries the upstream MIT notice, and includes Codex UI metadata. No upstream hooks, slash-command wrappers, personas, or automatic workflow activation are installed. Existing Jstack and delivery workflows continue to handle planning, testing, review, and shipping.

vendor/addyosmani.json pins the reviewed source and its file hashes. The integration review records all selection decisions, scenario checks, and the manual refresh procedure. Do not overwrite these adaptations with a raw upstream copy.

Match process to stakes: visually check a small style edit; verify a feature's behavior and failure states; use focused contract, migration, or security guidance for changes that cross those boundaries. A skill's presence never requires loading the whole collection or starting the full lifecycle.

Builder.io provenance and portability

The collection imports 24 skills from BuilderIO/skills at commit fecf1ffac18165d165bef520b5c6bd49553c7968. Builder.io released the source under the MIT license. Every imported directory includes that license notice so direct and portable installs retain it.

vendor/builderio.json records the source revision, inventory, shared resources, and integration changes. scripts/vendor_builderio.py reproduces the import and refuses an unreviewed skill inventory or name collision.

The integration keeps the upstream skill bodies while adding package-level portability:

• concise activation descriptions within the existing discovery budget
• standard metadata provenance, risk, owner, and capability fields
• agents/openai.yaml for explicit Codex discovery and invocation
• a complete MIT notice in every imported skill directory
• installed-tree-safe Factory references and bundled visual media
• the reviewed Dispatch MCP declaration used by the an workflow
• explicit compatibility notes and fail-closed setup behavior

No imported skill grants authority to authenticate, publish, reply, approve, merge, deploy, notify, install desktop software, enable capture, or expose a hosted artifact. The active user request, repository rules, runtime permissions, and Factory action policies remain in control.

The complete review and recommendations are in docs/BUILDERIO_REVIEW.md.

Updating the Builder.io import

Review upstream changes first, then use a clean checkout:

python3 scripts/vendor_builderio.py /path/to/BuilderIO-skills --replace
python3 -m myskills catalog > catalog/myskills.json
python3 -m pytest tests -q --ignore=tests/test_evidence.py
git diff --check

The vendor tool stops when upstream adds or removes a skill. Review the new inventory, dependencies, licenses, authority boundaries, and generated Agent-Native sources before changing the expected set.

Jstack provenance and hardening

The collection imports 64 unique skills from michael-denyer/pstack-claude v0.9.102 at commit 356c6e0f978df729eb16f227d795f34d221c5aad. Its duplicate unslop is excluded because this collection keeps the existing enhanced definition as the canonical skill.

vendor/jstack.json records the exact source, revision, 64 imported names, and exclusion. scripts/vendor_jstack.py rebuilds the import instead of relying on an undocumented manual copy.

The integration preserves the upstream design-first, evidence-driven methods while tightening assumptions that are too broad for a governed software factory:

• system, user, Mission Control, and repository rules override methods
• reversible actions still require authority when they write to external state
• team messages, ticket updates, eval launches, publishing, merging, deployment, spending, and destructive cleanup are not implicitly authorized
• experiments inform Product Owner decisions; they do not replace them
• PR playbooks produce a verified local handoff when publication is not allowed
• worktree cleanup never treats untracked files as disposable
• transcript tools stay inside the active harness and workspace
• multi-agent fan-out remains task-selected and harness-authorized

The complete integration rationale is in docs/JSTACK_REVIEW.md.

Updating Jstack

Review upstream release notes and breaking changes first. Then clone or fetch a clean upstream checkout and run:

python3 scripts/vendor_jstack.py /path/to/pstack-claude --replace
python3 -m myskills catalog > catalog/myskills.json
python3 -m pytest tests -q --ignore=tests/test_evidence.py
git diff --check

The vendor tool verifies the source remote and clean checkout, checks the reviewed inventory, and records the input revision. It stages frontmatter, Codex metadata, original-source regression tests, and authority-hardening changes before replacing the installed output. A changed anchor or conflicting metadata stops the refresh before those protections can disappear.

After a refresh, review:

1. vendor/jstack.json
2. every changed SKILL.md, script, and reference
3. upstream licenses and notices
4. cross-runtime tool mappings
5. external-write and approval boundaries
6. package tests and Mission Control lint scores

Repository structure

skillz/
├── plugin.json                    # Portable Agent Plugin metadata
├── .claude-plugin/                # Claude plugin and marketplace metadata
├── .codex-plugin/plugin.json      # Codex plugin metadata
├── .cursor-plugin/plugin.json     # Cursor plugin metadata
├── .mcp.json                      # Optional Agent-Native Dispatch declaration
├── .github/workflows/             # Validation and tagged-release jobs
├── agents/                        # Packaged companion agents
├── docs/                          # Import, governance, and recommendation reviews
├── scripts/
│   ├── check_release.py           # Release-version gate
│   ├── install_skills.py          # Conflict-safe runtime installer
│   ├── vendor_builderio.py        # Reproducible Builder.io import
│   └── vendor_jstack.py           # Reproducible Jstack build
├── skills/
│   └── <skill>/
│       ├── SKILL.md               # Canonical Agent Skill
│       ├── agents/openai.yaml      # Codex UI and invocation metadata
│       ├── references/             # Optional detailed guidance
│       └── scripts/                # Optional deterministic helpers
├── tests/                         # Package and workflow contracts
├── vendor/                        # Pinned inventories and generated map source
├── AGENTS.md                       # Repository execution policy
└── LICENSES.md                     # Per-source licensing map

Compatibility contract

Portable SKILL.md

The public Agent Skills fields are the portable source format:

• name
• description
• license
• compatibility
• metadata
• scalar allowed-tools

Descriptions state both what the skill does and when it should activate. Mission Control extensions such as version, owner, risk, and comma-separated capabilities live under metadata.

Claude Code

Claude Code discovers the standard SKILL.md tree. Per the Claude plugin reference, plugin installs also discover the definitions in agents/ under the software-factory-skills:<agent-name> namespace. Direct installs receive the same definitions in .claude/agents/ and use their bare names. Shared bodies must not assume that Claude-only tools exist in every harness. Plugin installs can also discover the Dispatch declaration in .mcp.json; direct skill copies do not modify Claude's connector configuration.

Codex

Codex uses the same skill bodies and reads agents/openai.yaml for display and explicit invocation. Jstack workflows consult skills/poteto-mode/references/harness-tools.md when Claude tool names need a Codex equivalent. The Codex plugin manifest also points at the optional Dispatch declaration. Authentication and app access are still user-controlled.

Cursor

Cursor can load the root Agent Plugin or the Cursor-specific manifest. User skill installs use ~/.cursor/skills/ so Cursor Cloud Agents can receive them. Project installs share .agents/skills/ with Codex and other compatible tools. The runtime map explains how to replace Claude-only worker and model fields.

Other runtimes

Other runtimes receive the same skill directories through --portable PATH. The runtime must discover standard Agent Skills or explicitly load the selected SKILL.md. The runtime map defines safe fallbacks when workers, task tracking, scheduled checks, or structured questions are unavailable.

Builder.io skills name their required host capabilities in compatibility. Runtimes may map equivalent tools, but they must not invent successful writes or bypass a missing connector. Factory skills read the bundled sibling guide; install the complete collection when using those modules.

Mission Control

Mission Control reads portable fields first and resolves optional governance metadata at the ingestion boundary. Legacy top-level Mission Control metadata can remain supported by the application, but new portable skills should not depend on it.

Authority model

Skills describe methods. They do not create authority.

The effective precedence is:

1. system and platform safety requirements
2. explicit user instructions and approvals
3. Mission Control execution contract
4. repository policy such as AGENTS.md or CLAUDE.md
5. selected skill guidance

Stop and request direction when a choice changes product behavior, expands scope, accepts failed evidence, or requires authority the active task does not provide. Continue through low-risk, reversible implementation details that are already inside the authorized contract.

Requirements

Most skills are Markdown-only. Individual workflows may need additional tools:

Run the evidence environment check before recording:

python3 skills/evidence-driven-testing/scripts/evidence.py doctor --json

Validation

The David Ondrej integration passed 164 portable Python tests, all five new skill frontmatter checks, source hash verification, catalog validation, and release metadata checks. The review report records the full-suite recorder failures caused by this host's missing dependencies and sandbox restrictions.

The October 25 refresh passed 158 portable Python tests, 264 imported Bun script tests, and two targeted recorder regressions. GitHub's package and browser checks also passed. The review report records reproduction controls and installation checks.

Install the single test dependency and run the portable suite:

python3 -m pip install pytest
python3 -m pytest tests -q --ignore=tests/test_evidence.py
python3 -m compileall -q scripts skills
python3 scripts/check_release.py v2.6.0
git diff --check

After changing skill content or provenance, regenerate and validate the catalog before running those checks:

python3 -m myskills catalog > catalog/myskills.json
python3 -m myskills validate

For changes to the imported orchestration or PR tools, run their local suite with Bun:

bun test skills/poteto-mode/scripts/check-plan.test.ts skills/poteto-mode/scripts/orch skills/poteto-mode/scripts/watch-pr

Run the complete suite on a host with the native evidence dependencies:

python3 -m pytest tests -q

The tests verify:

• exactly 108 canonical skill directories
• portable frontmatter and matching directory names
• concise activation descriptions within the package-wide discovery budget
• Codex metadata for every skill
• portable, Claude, Codex, and Cursor manifests for one package version
• the Claude marketplace entry and the tagged-release version gate
• packaged companion agents and valid plugin or direct-install routing
• local Markdown links
• pinned Jstack, Builder.io, Addy Osmani, and David Ondrej provenance and license retention
• standalone installation and source inventory checks for the David Ondrej adaptations
• isolated installation of every Addy adaptation with all local references
• Claude, Codex, Cursor, and custom-runtime installer destinations
• conflict refusal, backups, dry runs, copy mode, symlink mode, deduplication, and idempotency
• Greptile review freshness and bounded polling
• isolated Playwright dependency handling
• evidence recorder lifecycle on capable hosts

GitHub Actions runs the portable tests and Python syntax checks on every pull request and push to main. A v* tag must match every package manifest before the release job publishes source archives and SHA-256 checksums. Native recorder coverage remains host-specific because desktop capture and FFmpeg filter availability vary.

These package checks do not grant behavioral qualification. Catalog entries remain UNTRUSTED and NOT_EVALUATED until separately qualified. The refresh did not verify native recorder rendering or live media uploads. Rendering needs FFmpeg with the ass filter; GitHub attachments need an authenticated gh version that exposes --attach.

Adding a skill

1. Create skills/<skill-name>/SKILL.md.
2. Match the directory name and frontmatter name using lowercase letters, numbers, and hyphens.
3. Write a precise description covering behavior and activation conditions.
4. Keep portable fields at the top level and Mission Control governance values inside metadata.
5. Add skills/<skill-name>/agents/openai.yaml with a clear display name, a 25–64 character short description, and a default prompt naming $skill-name.
6. Keep SKILL.md focused. Put deep guidance in linked references and deterministic operations in scripts.
7. Declare the source and license. Do not broaden an upstream license.
8. Add or update tests and run the validation commands.

What is intentionally not automatic

• No unconditional startup hook injects the entire Jstack workflow.
• No skill is preloaded solely because it is installed.
• No same-name user skill is silently overwritten.
• No imported skill is automatically published to a registry.
• No direct installer silently configures MCP, downloads Clips, or enables capture.
• No multi-agent fan-out is enabled without a matching task and harness support.
• No skill can silently authorize external writes, merge, deployment, deletion, spending, or a Product Owner decision.

Sources and acknowledgements

• michaelshimeles/skills provides the repository history and original core collection.
• michael-denyer/pstack-claude provides the pinned upstream source used to build Jstack.
• BuilderIO/skills provides the pinned Builder.io, Agent-Native, and experimental Factory workflows under MIT.
• Cursor's upstream plugin is the original source of the methods distributed as Jstack.
• vercel-labs/before-and-after provides the visual-comparison workflow.
• greptileai/skills provides the Greptile review workflow.
• Agent Skills defines the portable skill format.
• Agent Plugins defines the portable package manifest.
• Claude plugin marketplaces, OpenAI's skill guide, and Cursor plugins define the runtime-specific distribution paths.

See LICENSES.md and the license files inside individual skill directories for exact terms.

MySkills governance foundation

The additive MySkills reference library inventories this collection with immutable package digests, provenance, explicit trust and qualification metadata. Run python3 -m myskills validate or inspect the generated catalog. Existing runtime installation is unchanged. Catalog inclusion grants no execution authority and does not establish qualification.