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.

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

• 8 core delivery, architecture, evidence, review, and writing skills
• 30 workflows for planning, implementation, review, and operations
• 23 engineering principles

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.

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 61 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.

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.

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 two 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

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.

Jstack provenance and hardening

The collection imports 53 unique skills from michael-denyer/pstack-claude v0.9.30 at commit 45f768349a6d7d7e71509fee3f5bccfad54b3bad. 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, 53 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 pytest tests -q
git diff --check

The vendor tool verifies the source remote and pinned commit, reapplies frontmatter and Codex metadata, and checks every authority-hardening anchor. It stops if upstream moves an anchor or introduces conflicting metadata so safety changes cannot disappear silently.

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
├── .github/workflows/             # Validation and tagged-release jobs
├── agents/                         # Packaged companion agents
├── docs/JSTACK_REVIEW.md          # Import and governance review
├── scripts/
│   ├── check_release.py           # Release-version gate
│   ├── install_skills.py          # Conflict-safe runtime installer
│   └── 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 inventory 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.

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.

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.

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

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.2.0
git diff --check

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

python3 -m pytest tests -q

The tests verify:

• exactly 61 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 provenance and hardening
• 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.

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 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.
• 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.