State Snapshot Instrumenter Agent Skill

Instrument programs (Python, C/C++, Java) to capture snapshots of key program states at runtime, including variables, memory, and call stacks. Use when you need to debug complex issues, reproduce test cases, prepare traces for formal verification, or analyze program execution. Supports manual instrumentation points, automatic function/method instrumentation, and conditional triggers. Outputs structured JSON snapshots for debugging, replay, and verification workflows.

19k tokens

context cost

the whole folder, loaded on every use

files

ships runnable scripts

copies elsewhere

how many repositories repackaged it

141

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/ArabelaTso/Skills-4-SE --skill state-snapshot-instrumenter

The instruction itself

22 sections, as written by the author

State Snapshot Instrumenter

Overview

This skill instruments programs to capture snapshots of key program states at runtime. Snapshots include variable values, memory state, call stacks, and execution context, saved in structured JSON format for analysis, debugging, reproduction, and verification.

Quick Start

Basic Workflow

Add snapshot markers to your code (manual mode) or use automatic instrumentation
Run the instrumenter to generate instrumented code
Execute the instrumented program to capture snapshots
Analyze snapshots to understand program behavior

Example: Python

# 1. Add markers to your code
# def my_function(x):
#     __SNAPSHOT__("my_function:start")
#     result = x * 2
#     __SNAPSHOT__("my_function:end")
#     return result

# 2. Instrument the code
python scripts/instrument_python.py my_program.py --mode manual

# 3. Run instrumented program
python my_program_instrumented.py
# Snapshots saved to snapshots.json

# 4. Analyze snapshots
python scripts/analyze_snapshots.py snapshots.json --list

Example: C/C++

# 1. Add markers to your code
# int main() {
#     __SNAPSHOT__("main:start");
#     int x = 10;
#     __SNAPSHOT__("main:end");
#     return 0;
# }

# 2. Instrument the code
python scripts/instrument_c.py program.c --mode manual

# 3. Compile with runtime
gcc program_instrumented.c scripts/snapshot_runtime.c -o program -rdynamic

# 4. Run and analyze
./program
python scripts/analyze_snapshots.py snapshots.json --list

Example: Java

# 1. Add markers to your code
# public static void main(String[] args) {
#     __SNAPSHOT__("main:start");
#     int x = 10;
#     __SNAPSHOT__("main:end");
# }

# 2. Instrument the code
python scripts/instrument_java.py Program.java --mode manual

# 3. Compile and run
cp scripts/SnapshotRuntime.java snapshot/
javac snapshot/SnapshotRuntime.java
javac Program_instrumented.java
java Program_instrumented

# 4. Analyze
python scripts/analyze_snapshots.py snapshots.json --list

Instrumentation Modes

Manual Mode (Recommended for Targeted Debugging)

Add explicit __SNAPSHOT__("location") markers at specific points in your code.

Python:

def process_data(items):
    __SNAPSHOT__("process_data:entry")

    result = []
    for item in items:
        __SNAPSHOT__("loop_iteration")
        result.append(item * 2)

    __SNAPSHOT__("process_data:exit")
    return result

C/C++:

int calculate(int x, int y) {
    __SNAPSHOT__("calculate:entry");

    int result = x + y;

    __SNAPSHOT__("calculate:exit");
    return result;
}

Java:

public int calculate(int x, int y) {
    __SNAPSHOT__("calculate:entry");

    int result = x + y;

    __SNAPSHOT__("calculate:exit");
    return result;
}

Instrument:

python scripts/instrument_python.py file.py --mode manual
python scripts/instrument_c.py file.c --mode manual
python scripts/instrument_java.py file.java --mode manual

Automatic Mode (Comprehensive Coverage)

Automatically instrument all function/method entry and exit points.

python scripts/instrument_python.py file.py --mode auto
python scripts/instrument_c.py file.c --mode auto
python scripts/instrument_java.py file.java --mode auto

This captures state at every function boundary without manual markers.

Core Operations

1. Instrumentation

Python:

# Manual mode
python scripts/instrument_python.py input.py --mode manual -o output.py

# Automatic mode
python scripts/instrument_python.py input.py --mode auto -o output.py

# In-place modification
python scripts/instrument_python.py input.py --mode manual --inplace

C/C++:

# Instrument
python scripts/instrument_c.py input.c --mode manual -o output.c

# Compile with runtime
gcc output.c scripts/snapshot_runtime.c -o program -rdynamic

# Run with custom output file
SNAPSHOT_OUTPUT=my_snapshots.json ./program

Java:

# Instrument
python scripts/instrument_java.py Input.java --mode manual -o Output.java

# Setup runtime
cp scripts/SnapshotRuntime.java snapshot/
javac snapshot/SnapshotRuntime.java

# Compile and run
javac Output.java
SNAPSHOT_OUTPUT=my_snapshots.json java Output

2. Snapshot Analysis

List all snapshots:

python scripts/analyze_snapshots.py snapshots.json --list

Show detailed snapshot:

python scripts/analyze_snapshots.py snapshots.json --show 5

View execution timeline:

python scripts/analyze_snapshots.py snapshots.json --timeline

Track variable changes:

python scripts/analyze_snapshots.py snapshots.json --track-var "user_id"

Compare two snapshots:

python scripts/analyze_snapshots.py snapshots.json --compare 10 20

Filter snapshots:

# By location
python scripts/analyze_snapshots.py snapshots.json --filter-location "main"

# By type
python scripts/analyze_snapshots.py snapshots.json --filter-type "function_entry"

3. Runtime Control

Python:

import snapshot_runtime

# Disable snapshots temporarily
snapshot_runtime.disable()
# ... performance-critical code ...
snapshot_runtime.enable()

# Set custom output file
snapshot_runtime.set_output_file("custom.json")

# Manually save snapshots
snapshot_runtime.save_snapshots()

C/C++:

#include "snapshot_runtime.h"

snapshot_disable();
// ... performance-critical code ...
snapshot_enable();

snapshot_finalize();  // Manually save

Java:

import snapshot.SnapshotRuntime;

SnapshotRuntime.disable();
// ... performance-critical code ...
SnapshotRuntime.enable();

SnapshotRuntime.setOutputFile("custom.json");
SnapshotRuntime.saveSnapshots();

Use Cases

Bug Debugging

Capture comprehensive state to understand complex bugs:

Instrument with automatic mode for full coverage
Run to reproduce the bug
Analyze snapshots to identify failure point
Track variable changes to understand root cause

See references/use_cases.md for detailed debugging workflows.

Test Case Reproduction

Extract exact inputs and state to reproduce failures:

Instrument with manual snapshots at key points
Capture failing execution
Extract input dependencies from snapshots
Reconstruct minimal test case

See references/use_cases.md for reproduction workflows.

Formal Verification

Generate execution traces for verification tools:

Instrument function boundaries
Collect execution traces
Extract invariants and contracts
Feed to verification tools

See references/use_cases.md for verification workflows.

Reference Documentation

references/instrumentation_guide.md - Comprehensive guide on instrumenting programs, including language-specific instructions, best practices, and troubleshooting
references/snapshot_format.md - Complete specification of the JSON snapshot format, including language-specific variations and serialization rules
references/use_cases.md - Detailed workflows for debugging, reproduction, verification, performance analysis, and concurrency debugging

Example Programs

Example instrumented programs are provided in assets/:

example_python.py - Python example with manual snapshots
example_c.c - C example with manual snapshots
example_java.java - Java example with manual snapshots

Output Format

All snapshots are saved in unified JSON format:

{
  "format_version": "1.0",
  "language": "python",
  "total_snapshots": 5,
  "snapshots": [
    {
      "snapshot_id": 1,
      "timestamp": "2026-02-17T19:30:45",
      "location": "main:start",
      "type": "manual",
      "call_stack": [...],
      "local_variables": {...}
    }
  ]
}

See assets/snapshot_schema.json for the complete JSON schema.

Tips

Use manual mode for targeted debugging to minimize overhead
Use automatic mode for comprehensive execution understanding
Disable snapshots in performance-critical sections
Use descriptive location names (e.g., "function:entry", "after_operation")
Set custom output files with SNAPSHOT_OUTPUT environment variable
Analyze snapshots incrementally as you debug
Compare snapshots to identify when state becomes incorrect
Track key variables through execution to understand data flow

Other skills for the same job

different authors, same section of the catalogue

MCP Builder

by anthropics

vendor ×13

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.

774 tokens

Finishing A Development Branch

by ZhanlinCui

×7

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup

Vercel React Native Skills

by vercel-labs

vendor ×6

React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.

39k tokens

Vercel React Best Practices

by ratacat

×5

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification

1k tokens

How to use it

Copy the folder

Take arabelatso/state-snapshot-instrumenter from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.