SkillAgentSearch skills...

gepetto

Creates detailed, sectionized implementation plans through research, stakeholder interviews, and multi-LLM review

Install / Use

npx skills add softaworks/agent-toolkit --skill gepetto

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

85/100

Supported Platforms

Zed

Our assessment of gepetto

gepetto scores 85/100 on our quality scale, 587th of 950 AI & Machine Learning skills we index.

Its SKILL.md is 10 KB long, well organised into 23 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.

With 2,502 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
14/20
Freshness
11/15

Maintenance, license and trust

  • The repository was last updated about 9 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
  • Our last check on 2026-11-04 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 94/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-10-01. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

gepetto compared with similar skills

All 4 of these similar skills score higher than gepetto; compare them before choosing.

SkillScoreStarsUpdatedFormat
gepetto (this skill)by softaworks852.5k9mo agoSKILL.md
claude-memby thedotmack100117.6ktodayCLAUDE.md
Understand-Anythingby Egonex-AI10092.8k1d agoCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
CowAgentby zhayujie10048.0ktodayCLAUDE.md

Frequently asked questions

How do I install gepetto?
Run npx skills add softaworks/agent-toolkit --skill gepetto. The install tabs above show the steps for each supported agent.
Which AI agents does gepetto work with?
It is written for Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
Is gepetto safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 94/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is gepetto still maintained?
The repository was last updated about 9 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.

name: gepetto description: Creates detailed, sectionized implementation plans through research, stakeholder interviews, and multi-LLM review. Use when planning features that need thorough pre-implementation analysis.

Gepetto

Orchestrates a multi-step planning process: Research → Interview → Spec Synthesis → Plan → External Review → Sections

CRITICAL: First Actions

BEFORE anything else, do these in order:

1. Print Intro

Print intro banner immediately:

═══════════════════════════════════════════════════════════════
GEPETTO: AI-Assisted Implementation Planning
═══════════════════════════════════════════════════════════════
Research → Interview → Spec Synthesis → Plan → External Review → Sections

Note: GEPETTO will write many .md files to the planning directory you pass it

2. Validate Spec File Input

Check if user provided @file at invocation AND it's a spec file (ends with .md).

If NO @file was provided OR the path doesn't end with .md, output this and STOP:

═══════════════════════════════════════════════════════════════
GEPETTO: Spec File Required
═══════════════════════════════════════════════════════════════

This skill requires a markdown spec file path (must end with .md).
The planning directory is inferred from the spec file's parent directory.

To start a NEW plan:
  1. Create a markdown spec file describing what you want to build
  2. It can be as detailed or as vague as you like
  3. Place it in a directory where gepetto can save planning files
  4. Run: /gepetto @path/to/your-spec.md

To RESUME an existing plan:
  1. Run: /gepetto @path/to/your-spec.md

Example: /gepetto @planning/my-feature-spec.md
═══════════════════════════════════════════════════════════════

Do not continue. Wait for user to re-invoke with a .md file path.

3. Setup Planning Session

Determine session state by checking existing files:

  1. Set planning_dir = parent directory of the spec file

  2. Set initial_file = the spec file path

  3. Scan for existing planning files:

    • claude-research.md
    • claude-interview.md
    • claude-spec.md
    • claude-plan.md
    • claude-integration-notes.md
    • claude-ralph-loop-prompt.md
    • claude-ralphy-prd.md
    • reviews/ directory
    • sections/ directory
  4. Determine mode and resume point:

| Files Found | Mode | Resume From | |-------------|------|-------------| | None | new | Step 4 | | research only | resume | Step 6 (interview) | | research + interview | resume | Step 8 (spec synthesis) | | + spec | resume | Step 9 (plan) | | + plan | resume | Step 10 (external review) | | + reviews | resume | Step 11 (integrate) | | + integration-notes | resume | Step 12 (user review) | | + sections/index.md | resume | Step 14 (write sections) | | all sections complete | resume | Step 15 (execution files) | | + claude-ralph-loop-prompt.md + claude-ralphy-prd.md | complete | Done |

  1. Create TODO list with TodoWrite based on current state

Print status:

Planning directory: {planning_dir}
Mode: {mode}

If resuming:

Resuming from step {N}
To start fresh, delete the planning directory files.

Logging Format

═══════════════════════════════════════════════════════════════
STEP {N}/17: {STEP_NAME}
═══════════════════════════════════════════════════════════════
{details}
Step {N} complete: {summary}
───────────────────────────────────────────────────────────────

Workflow

4. Research Decision

See research-protocol.md.

  1. Read the spec file
  2. Extract potential research topics (technologies, patterns, integrations)
  3. Ask user about codebase research needs
  4. Ask user about web research needs (present derived topics as multi-select)
  5. Record which research types to perform in step 5

5. Execute Research

See research-protocol.md.

Based on decisions from step 4, launch research subagents:

  • Codebase research: Task(subagent_type=Explore)
  • Web research: Task(subagent_type=Explore) with WebSearch

If both are needed, launch both Task tools in parallel (single message with multiple tool calls).

Important: Subagents return their findings - they do NOT write files directly. After collecting results from all subagents, combine them and write to <planning_dir>/claude-research.md.

Skip this step entirely if user chose no research in step 4.

6. Detailed Interview

See interview-protocol.md

Run in main context (AskUserQuestion requires it). The interview should be informed by:

  • The initial spec
  • Research findings (if any)

7. Save Interview Transcript

Write Q&A to <planning_dir>/claude-interview.md

8. Write Initial Spec (Spec Synthesis)

Combine into <planning_dir>/claude-spec.md:

  • Initial input (the spec file)
  • Research findings (if step 5 was done)
  • Interview answers (from step 6)

This synthesizes the user's raw requirements into a complete specification.

9. Generate Implementation Plan

Create detailed plan → <planning_dir>/claude-plan.md

IMPORTANT: Write for an unfamiliar reader. The plan must be fully self-contained - an engineer or LLM with no prior context should understand what we're building, why, and how just from reading this document.

10. External Review

See external-review.md

Launch TWO subagents in parallel to review the plan:

  1. Gemini via Bash
  2. Codex via Bash

Both receive the plan content and return their analysis. Write results to <planning_dir>/reviews/.

11. Integrate External Feedback

Analyze the suggestions in <planning_dir>/reviews/.

You are the authority on what to integrate or not. It's OK if you decide to not integrate anything.

Step 1: Write <planning_dir>/claude-integration-notes.md documenting:

  • What suggestions you're integrating and why
  • What suggestions you're NOT integrating and why

Step 2: Update <planning_dir>/claude-plan.md with the integrated changes.

12. User Review of Integrated Plan

Use AskUserQuestion:

The plan has been updated with external feedback. You can now review and edit claude-plan.md.

If you want Claude's help editing the plan, open a separate Claude session - this session
is mid-workflow and can't assist with edits until the workflow completes.

When you're done reviewing, select "Done" to continue.

Options: "Done reviewing"

Wait for user confirmation before proceeding.

13. Create Section Index

See section-index.md

Read claude-plan.md. Identify natural section boundaries and create <planning_dir>/sections/index.md.

CRITICAL: index.md MUST start with a SECTION_MANIFEST block. See the reference for format requirements.

Write index.md before proceeding to section file creation.

14. Write Section Files — Parallel Subagents

See section-splitting.md

Launch parallel subagents - one Task per section for maximum efficiency:

  1. First, parse sections/index.md to get the SECTION_MANIFEST list
  2. Then launch ALL section Tasks in a single message (parallel execution):
# Launch all in ONE message for parallel execution:

Task(
  subagent_type="general-purpose",
  prompt="""
  Write section file: section-01-{name}

  Inputs:
  - <planning_dir>/claude-plan.md
  - <planning_dir>/sections/index.md

  Output: <planning_dir>/sections/section-01-{name}.md

  The section file must be COMPLETELY SELF-CONTAINED. Include:
  - Background (why this section exists)
  - Requirements (what must be true when complete)
  - Dependencies (requires/blocks)
  - Implementation details (from the plan)
  - Acceptance criteria (checkboxes)
  - Files to create/modify

  The implementer should NOT need to reference any other document.
  """
)

Task(
  subagent_type="general-purpose",
  prompt="Write section file: section-02-{name} ..."
)

Task(
  subagent_type="general-purpose",
  prompt="Write section file: section-03-{name} ..."
)

# ... one Task per section in the manifest

Wait for ALL subagents to complete before proceeding.

15. Generate Execution Files — Subagent

Delegate to subagent to reduce main context token usage:

Task(
  subagent_type="general-purpose",
  prompt="""
  Generate two execution files for autonomous implementation.

  Input files:
  - <planning_dir>/sections/index.md (has SECTION_MANIFEST)
  - <planning_dir>/sections/section-*.md (all section files)

  OUTPUT 1: <planning_dir>/claude-ralph-loop-prompt.md
  For ralph-loop plugin. EMBED all section content inline.

  Structure:
  - Mission statement
  - Full content of sections/index.md
  - Full content of EACH section file (embedded, not referenced)
  - Execution rules (dependency order, verify acceptance criteria)
  - Completion signal: <promise>ALL-SECTIONS-COMPLETE</promise>

  OUTPUT 2: <planning_dir>/claude-ralphy-prd.md
  For Ralphy CLI. REFERENCE section files (don't embed).

  Structure:
  - PRD header
  - How to use (ralphy --prd command)
  - Context explanation
  - Checkbox task list: one "- [ ] Section NN: {name}" per section

  Write both files.
  """
)

Wait for subagent completion before proceeding.

16. Final Status

Verify all files were created successfully:

  • All section files from SECTION_MANIFEST
  • claude-ralph-loop-prompt.md
  • claude-ralphy-prd.md

17. Output Summary

Print generated files and next steps:

═══════════════════════════════════════════════════════════════
GEPETTO: Planning Complete
═══════════════════════════════════════════════════════════════

Generated files:
  - claude-research.md (research findings)
  - claude-interview.md (Q&A transcript)
  - claude-spec.md (synthesized specification)
  - claude-plan.md (implementation plan)
  - claude-integration-notes.md (feedback decisions)
  - reviews/ (external LLM feedback)
  - sections/ (implementation units)
  - claude-ralph-loop-prompt.md (for ralph-loop plugin)
  - claude-ralphy-prd.md (for Ralphy CLI)

How to implement:

Option A - Manual (recommended for learning/control):
  1. Read sections/index.md to understand dependencies
  2. Implement each section file in order
  3. Each section is self-contained with acceptance criteria

Option B - Autonomous with ralph-loop (Claude Code plugin):
  /ralph-loop @<planning_dir>/claude-ralph-loop-prompt.md --completion-promise "COMPLETE" --max-iterations 100

Option C - Autonomous with Ralphy (external CLI):
  ralphy --prd <planning_dir>/claude-ralphy-prd.md
  # Or: cp <planning_dir>/claude-ralphy-prd.md ./PRD.md && ralphy
═══════════════════════════════════════════════════════════════

Related Skills

View on GitHub
GitHub Stars2.5k
CategoryAI
Updated8mo ago
Forks229

Languages

Python

Trust signals

94/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 low