steplock 0.3.0

An MCP server gatekeeper runtime that enforces step-by-step AI skill execution with output verification, ensuring stable and reliable agent workflows regardless of LLM compliance.

StepLock

An MCP server gatekeeper runtime that enforces step-by-step AI skill execution with output verification.

AI agents skip steps. They mis-sequence workflows. They accept incorrect output and keep going. StepLock fixes that by sitting between your agent and its skill definitions — delivering one step at a time, requiring submitted output, and running verification scripts before advancing. Reliable, auditable execution regardless of LLM compliance.

---

How it works

Agent  ──►  StepLock (MCP)  ──►  Step 1 instruction
                │
         Agent submits output
                │
         Verification script runs
                │
         ✔ Pass → next step    ✗ Fail → guidance returned, agent retries

StepLock exposes four MCP tools to the agent:

Tool	Purpose
list_skills	Discover available skills by name and description
start_skill	Begin execution — returns session ID, first step, and available helpers
submit_step_output	Submit output for the current step and receive the next
run_helper_script	Run a helper script declared on the current step

---

Quick start

VS Code / Copilot

Add to .vscode/mcp.json (workspace-scoped) or open MCP: Open User Configuration from the Command Palette:

{
  "servers": {
    "steplock": {
      "type": "stdio",
      "command": "uvx",
      "args": ["steplock"]
    }
  }
}

Verify the server is running: open Copilot Chat → Select tools → confirm list_skills, start_skill, submit_step_output, and run_helper_script are listed.

---

Defining a skill

my-skill/
├── SKILL.yaml
├── steps/
│   ├── step1.md
│   └── step2.md
└── scripts/
    ├── verify_step1.py
    └── get_context.py

SKILL.yaml

name: my-skill
description: When and why to use this skill.

steps:
  - id: step-1
    instruction: steps/step1.md     # file path or inline string
    verify: scripts/verify_step1.py # optional
    on_fail: retry                  # retry | abort (default: abort)
    helpers:                        # optional list of helper scripts
      - scripts/get_context.py

  - id: step-2
    instruction: steps/step2.md
    # no verify — output is accepted immediately

Verification scripts receive the agent's submitted output via stdin and exit with:

• 0 — output accepted, execution advances
• non-zero — output rejected; anything printed to stdout/stderr is returned to the agent as guidance

Helper scripts are utility scripts the agent can run during a step via run_helper_script to gather context or perform preparatory work. They are declared per-step with the helpers list and identified by filename without extension. They receive optional string arguments via sys.argv and return stdout, stderr, and exit_code.

---

Registering skills

StepLock discovers skills through two merged sources, each supporting auto-discovery:

Location	Created automatically	Auto-discovery	Purpose
~/.steplock/	Yes — on first run	✔ Recursively scans subdirectories	User-wide skills
./.steplock/	No	✔ Recursively scans subdirectories	Project-local skills

Auto-discovery

Place skill directories directly inside either location. StepLock recursively scans for SKILL.yaml files:

.steplock/
├── skills-registry.yaml           # explicit paths (optional)
├── my-skill/
│   └── SKILL.yaml
└── skill-pack/
    ├── skill-a/
    │   └── SKILL.yaml
    └── skill-b/
        └── SKILL.yaml

Explicit registry (optional)

# ~/.steplock/skills-registry.yaml  (or ./.steplock/skills-registry.yaml)
skills:
  - /home/user/my-skills/my-skill
  - /home/user/my-skills/another-skill

Registry entries can be:

• Skill directories — containing a SKILL.yaml file
• Folder paths — recursively scanned for SKILL.yaml files

Deduplication

If the same skill name appears in multiple locations, the project-local entry (./.steplock/) takes precedence over the user-wide entry (~/.steplock/). Filesystem paths are never exposed to the agent — only skill names.

---

Skill definition reference

Field	Required	Description
name	✔	Unique skill name exposed to the agent
description	✔	When and why the agent should use this skill
steps[].id	✔	Unique step identifier
steps[].instruction	✔	File path (relative to skill dir) or inline string
steps[].verify	—	Path to a verification script
steps[].on_fail	—	retry or abort (default: abort)
steps[].helpers	—	List of helper script paths (relative to skill dir)

Backward compatibility: a single-step skill with no verify behaves identically to an Anthropic-model skill. Existing skills adopt with zero changes.

---

Development setup

git clone https://github.com/l0kifs/steplock-ai-skill-executor.git
cd steplock-ai-skill-executor
uv sync

Connect to VS Code / Copilot from a local checkout — add to .vscode/mcp.json:

{
  "servers": {
    "steplock": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "steplock.entry_points.main"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Run tests:

uv run pytest tests/ -v          # Run all tests
uv run pytest tests/e2e/ -v      # E2E tests only
uv run pytest tests/unit/ -v     # Unit tests only

Tests use an in-memory transport — no running server instance required.

---

Contributing

Bug reports and pull requests are welcome. Before opening a PR:

1. Fork the repo and create a feature branch
2. Run uv run pytest — all tests must pass
3. Run uv run ruff check src/ — no lint errors
4. Open a pull request with a clear description of the change

For larger features, open an issue first to discuss the approach.

---

License

MIT © Sergei Konovalov