Skip to content
Skills Library
AI & agents · Automation

execute-steps

/execute-steps

Use when a skill needs step tracking, progress visibility, and resume support within a single phase. Called by skills, not directly by users.

Repository
tesseract ↗
Licence
MIT
Last repository change
22.06.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.06.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when a skill needs step tracking, progress visibility, and resume support within a single phase. Called by skills, not directly by users.

Original author description

Use when a skill needs step tracking, progress visibility, and resume support within a single phase. Called by skills, not directly by users.

How it works

  1. When to Use
  2. When NOT to Use
  3. Quick Reference
  4. Where steps.json lives
  5. Mandatory vs Conditional Steps
  6. Common Mistakes
Original SKILL.md headings · 57 lines, 568 words
SKILL.md preview
---
name: execute-steps
description: Use when a skill needs step tracking, progress visibility, and resume support within a single phase. Called by skills, not directly by users.
---

# Execute Steps

Thin step-tracking utility for individual Shield skills. Each skill defines a fixed skeleton of mandatory steps, then drives `shield/scripts/steps_store.py` to register them and update status. The script writes `steps.json` to the exact path the session-start hook reads, so an interrupted run can be offered for resume.

**This is NOT a cross-phase orchestrator.** Each skill calls the script independently for its own work.

**Never hand-write `steps.json` with the Write tool.** Always go through `steps_store.py` — it computes the correct path and the correct schema. Hand-writing puts the file where the hook can't find it.

## When to Use

- Called by a skill at startup to register its step skeleton
- Called by a skill after each step to update status
- Called by a skill to check for and resume interrupted work

## When NOT to Use

- Directly by users — skills call this, not users
- As a cross-phase pipeline — each skill manages its own phase

## Quick Reference

Run with `uv run shield/scripts/steps_store.py <cmd>`. The script resolves the path itself — pass no path.

| Lifecycle Hook | Command |
|----------------|---------|
| **Startup** | `read` first → if it returns an incomplete doc, offer resume or fresh; then `init --skill <name> --feature <slug> --steps-json '<json array>'` |
| **Before step** | `start <id>` |
| **After step** | `complete <id> [--output <path>]` — or `fail <id>` → stop |
| **All done** | `clear` |

The `--steps-json` array holds the skeleton — each step is `{"id": N, "action": "...", "mandatory": true}`. Conditional steps add `"mandatory": false`; `init` defaults status to `pending` and `mandatory` to `true`. See `--help` for all flags.

## Where steps.json lives

`steps_store.py` resolves it to `${SHIELD_HOME:-~/.shield}/projects/<project>/steps.json`, where `<project>` comes from the nearest `.shield.json`. This is the path the session-start hook reads. **You do not compute or type this path** — the script does.

On resume, the session-start hook shows: `Incomplete: research phase (step 2/5 — Research agents). Run the skill command to resume.` The skill then runs `read` and asks: "Resume from step 2 or start fresh?"

## Mandatory vs Conditional Steps

- **Mandatory** steps always run — no exceptions, even under time pressure
- **Conditional** steps (`"mandatory": false`) evaluate their condition at startup and are omitted from the `init` skeleton if not met
- Conditions are evaluated once at registration, not re-evaluated mid-run

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Hand-writing `steps.json` with the Write tool | Always use `steps_store.py` — it owns the path and schema |
| Typing the path yourself (e.g. `~/.shield/shield/<project>/`) | Never type the path — the script resolves it. The literal `shield/<project>` form is wrong; the hook reads `projects/<project>` |
| Skipping mandatory steps because "the context is clear enough" | Mandatory steps always run — conditions only apply to non-mandatory steps |
| Not running `read` before `init` | Always check first — an interrupted run should be offered for resume |
| Leaving `steps.json` after all steps complete | Run `clear` on completion — stale state causes false resume prompts |
| Treating execute-steps as the entry point | Skills are the entry point — this script is a utility they call, not an orchestrator |
| Relying on steps.json for loop iteration tracking | steps.json tracks coarse workflow position. For loops (e.g., per-AC), use the domain artifact (plan.json) as the per-item source of truth |

Versions

The database has no other skills named execute-steps.

Database snapshot: 13.11.2026 · package version 5e0245ec2a14 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100continue
    Resume work from a prior session by reading phase progress files in .claude/memory/ and active plans. Use this when starting a new session on in-progress work, or when the user says "continue", "pick up where I left off", "resume", or "what was I working on".
  • 91do-in-steps
    Execute one complex task as ordered, dependent steps run sequentially, passing context from each step to the next, with per-step LLM-as-a-judge verification. Use when later steps depend on the results of earlier ones.
  • 1003a-track
    Use when a developer wants to check progress, understand where they are in their agent project, or figure out what to do next. Reads the roadmap and project state, then provides a status report with next steps. Triggers on: "where am I", "what's next", "status", "progress",…
  • 100powerloop
    This skill should be used when the user runs /powerloop, asks to set up an automated task loop, wants iterative refactoring with quality checks, or needs to automate multi-step feature implementation across many files. It creates a cron-based schedule with Plan, Execute, Review,…
  • 96writing-skills
    Create or edit a skill (SKILL.md) when the user asks for one.
  • 100writing-skills
    Writes or tightens a Claude Code skill: short description, tight steps, tested triggers. Use when the user asks to create, write, improve or shrink a SKILL.md or a project skill, or says a skill never fires. Not for using a skill.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.