pskill

Run agent skills as programs, not as long text. A normal skill is a text file that asks your coding agent (Claude Code, Codex, and others) to follow some steps. A pskill skill is a map of steps, and a small program (the runner) gives the agent one step at a time. The agent cannot skip a step or change the order.

The example skill implement-issue in the viewer. Each box is one step, and the arrows show where each step can go next.

https://guplem.github.io/pskill/

Open it in Chrome or Edge. On the Folders tab, pick your project folder, or a folder of clones and worktrees. You then see every run and every skill in them. Your files stay on your computer: the page reads them in the browser.

Agents often skip a step of a long skill, forget a value, or jump ahead. With pskill, the runner keeps the order and the values. The agent only does the current step.

1. You ask your agent for a task, for example "implement issue 42".
2. The agent starts the matching skill. One use of a skill is a run.
3. The runner gives the agent one step. The agent does it and sends back its answer.
4. The runner checks the answer and gives the next step. If the answer is incomplete, the agent must fix it.
5. This repeats until the skill ends. When a step needs your decision, the agent asks you.

• uv, a small tool that installs everything else (Python included).
• git. The example skills also use the GitHub CLI (gh).

In the main folder of your project, run:

uv run https://raw.githubusercontent.com/guplem/pskill/main/pskill.py init

This creates a small .pskill/ folder. Commit it to git. Its file pskill.py names the pskill version. The first time someone runs it, it downloads that version once, so your teammates install nothing.

To move to the newest version later (this changes one line in .pskill/pskill.py):

uv run .pskill/pskill.py update

• One small file per skill (SKILL.md in .claude/skills/ and .agents/skills/). Your agent finds the skill through it. It holds the skill's goal and tells the agent how to use the runner.
• Two hooks (commands that your agent app runs by itself):
  • When the agent tries to stop while a step is still open, the hook tells it to continue. After 3 tries, it lets the agent stop and pauses the run. In Claude Code, an agent that waits on background work runs wait first: then the hook lets it stop, and the run stays open.
  • When you open a session, the hook updates the small skill files.
• One permission rule, so your agent app does not ask you each time the agent talks to the runner. It allows only uv run .pskill/pskill.py ....
• One small agent file per tool profile that your skills use (.claude/agents/pskill-read.md, for a block with tools: read). Each lists a few tools and nothing else, so a subagent that only reads code starts with a smaller context. Claude Code sees a new .claude/agents/ folder only after you open a new session.

Claude Code and Codex use the hooks only after you trust the project folder. Codex also asks you once to approve each hook (type /hooks). If your project builds its settings files with its own script, set hook_files in .pskill/config.yaml.

Ask your agent for the task. The skill starts by itself. Answer its questions.

You can also use the runner yourself. Each command starts with uv run .pskill/pskill.py:

The viewer shows each skill as a graph of steps, and each run as the path that it took. Click a step to see its details. You can edit skills and agents there, replay a run step by step, cancel a run, and delete finished runs.

The hosted viewer shows the same screens without a command, for many projects at once: open https://guplem.github.io/pskill/ in Chrome or Edge (see Open the viewer, with no install), and pick your project folders on the Folders tab. A folder of clones and worktrees works too: the viewer finds each project in it, and names the folder and the branch of every run. Your files stay on your computer.

.pskill/skills/ holds skills for the daily work on a GitHub project. Copy the ones you want into your own .pskill/skills/ (with the agents in .pskill/agents/), run sync, and adapt them.

The skills read your project's rules from its own files, so they work in most repositories as they are. They call GitHub through its REST API, so they also run in Claude Code cloud sessions, whose GitHub proxy refuses GraphQL. These settings make them work best:

• Run CI only on ready pull requests. implement-issue pushes many commits to a draft, and marks it ready at the end. In each pull request workflow, start the checks on ready_for_review too, skip drafts, and let a new push cancel the older run:

  on:
    pull_request:
      types: [opened, synchronize, reopened, ready_for_review]
  concurrency:
    group: checks-${{ github.ref }}
    cancel-in-progress: true
  jobs:
    checks:
      if: github.event_name != 'pull_request' || !github.event.pull_request.draft

• Name your fast checks in AGENTS.md (or CLAUDE.md, or the README): the lint, type check, and test commands. The skills run them before each push, and leave slow suites to CI.
• Use the labels:
  • A label that starts with waiting-for- (for example waiting-for-design) holds an issue: implement-issue does not start on it.
  • implement-issue adds waiting-for-human-review to a pull request that a person must look at before the merge. It creates the label when it is missing.
  • In autonomous mode, create-issue adds waiting-for-human-check to an issue that no person has read yet.
• Protect the default branch: require the CI checks and one approval. The skills never merge, so a person always does.
• Record your decisions in adr/ or docs/adr/ (one file per decision). The skills check a change against them.
• Work in a clean checkout. The skills stop when the checkout has uncommitted changes, because those changes are yours. They expect the GitHub remote to be named origin.
• Add your own reviewers. Each reviewer is one row in the review block of review-round (the one round that review-pr and implement-issue run), with an optional when, for example a database reviewer when the change touches your migrations.

This repository follows the same setup, with two differences: it requires no approval (it has one maintainer), and its decisions live in SPEC.md section 3, which AGENTS.md names.

Read AUTHORING.md, or run uv run .pskill/pskill.py authoring. The example skills are working examples of every feature.

• Autonomous mode asks you nothing. The agent also takes decisions that normally need you, like "close this issue". Only your agent app's permission settings protect you then.
• Codex needs "Full access". Its sandbox (the area that limits what commands can do) stops the runner from sending answers. Choose "Full access" in Codex's permissions menu, or start it with codex --sandbox danger-full-access. This turns off the sandbox for every command, not only for pskill.
• One session per folder, in apps other than Claude Code and Codex. There, two sessions in the same folder share the hooks.
• wait needs an app that wakes the agent when a background command ends. Claude Code does: with no time limit on your computer, and up to 30 minutes by default in a cloud session. Codex does not say that it does, so there the hook ignores waits and works as before: 3 refused stops, then a pause.
• pskill trusts the agent when it says that you answered a question.
• The steps are plain files. The agent could read the later steps. This is not a security barrier.

• The skill does not start: run uv run .pskill/pskill.py sync, then open a new session.
• You lost a run: run runs --open, then current <run>.
• A run is paused: the message says why. Fix the cause, then run resume <run>.
• update refuses to run: someone edited a runner file by hand. Undo it, or run update --force.

See AGENTS.md and the full design in SPEC.md.

MIT. See LICENSE.