gpsaggese/helpers / .claude/skills/review.create_demo
review.create_demo
VerifiedGoal
- Given a dir that holds a tool, write
code_demo.mdin that dir - The file has four parts:
- What the tool does, in a few lines
- What to run: the command, its needs, its cost, and how long it takes
- What is generated: each output file, what it holds, and the stage that writes it
- What a past run gave, and how to check the output
- Keep it short: a reader must run the demo after reading it for 5 mins
- It is the source of the end-to-end demo in
code_tour.md. The skill.claude/skills/review.create_code_tour/SKILL.mdpoints to this file and does not repeat it
Conventions
- Follow the template
.claude/templates/review_create_demo.template.md - Follow
.claude/skills/text.rules.mdand.claude/skills/markdown.rules.md - Name each file in backticks, with its path from the repo root
- Put each command in a fenced
bashblock, with>before the command - Take facts from the dir's README and from the files a run leaves. If a fact is
not clear, write
unknownand do not guess
Workflow
Get the Input
- Take the dir from the arguments. If none is given, use the current dir
- If the dir does not exist, report the error and stop
- Write
code_demo.mdin the dir. The name is fixed, so it does not follow## Generated File Namingof.claude/skills/skill.rules.md- If the file exists, read it, then overwrite it
- Take the dir's
README.md- If it does not exist, report the error and stop. Tell the user to run
.claude/skills/readme_dir.create/SKILL.mdon the dir first
- If it does not exist, report the error and stop. Tell the user to run
Find the Demo
- Find the runner: the executable that runs all stages, or the only executable
- Take its path, flags, and example commands from the README of the dir and of the script
- Check the flags with
--help
- Find the small example input: the smallest input file that the README or the tests
use, e.g.,
paper_list.short.csv- Skim the whole file, so the text says what the rows are
- Choose the output dir: take it from the README if it gives one. Else use
./run_demo, a dir in the current dir - Find the setup the command needs, e.g.,
PYTHONPATH, an API key, or Docker. Take it from the README of the dir - Find what the demo needs and costs
- Name the needs: internet, an LLM, a browser, an API key
- Say that the demo costs LLM calls when it calls an LLM
- Do not run a command that costs money. Ask the user to run it
- If the runner has
--dry_run, run it. Check that it needs no internet, no LLM, and no browser
Find What Is Generated
- Take the output file list from the README of the dir, e.g., from the section "Output Dir"
- If the demo's output dir exists, list it and compare it with the README:
> find <OUTPUT_DIR> -maxdepth 3 | sort- Keep only the files the demo makes
- Open and add any file in the output dir that the README does not list
- If a README file is missing from the output dir, say it is made only in some cases, and when
- For each file or group, write:
- The name, with
<BASE>orNNas in the README - What it holds, in one short line. Open the file if the README is not clear
- The stage that writes it
- The name, with
- Cover the results, the issues, the summaries, and the cache and logs
- If the output dir exists, take the past-run counts from the summary files
- For each stage, take the items processed, completed, failed, and the issues
- Take one or two values from a result file, e.g., a rating
Write the File
- Fill the template in this order:
# What the Tool Does: purpose, input, and output, in 3 bullets# Run the Demo: needs, cost, time, the command, and the dry run# What Is Generated: the tree of the output dir, and the table of files# Example Result: the past-run counts, one row per stage# Check the Output: the checks a reader can fail
- Use the table columns
File,Written by, andContent - Write the example result only when an output dir exists
- Say it is the result of a past run
- Say the numbers can change with the internet and the LLM, but the files do not
- In
# Check the Output, write these checks when they apply:- Each summary file shows the counts of its stage
- Each failed item is in the issues file of the same stage
- A value of the report equals the value in one item's file
- A second run of the same command skips the finished work
- Do not add a diagram. The file is short text
Report
- Print the file path, the demo command, what it needs, and what it costs
- Print the list of files the demo makes
- Do not commit the file
Constraints
- Do not modify any file of the dir except
code_demo.md. Delete the*.logfiles that a run created - Do not run a command that needs internet, an LLM, or a browser without the user
- Do not invent a command, a flag, a file, or a number
- Use
:and not-to separate a file from its description - Do not use emojis or the em-dash
Examples
- Run on the dir
research/Estimate_academic_paper_quality- The runner is
estimate_paper_quality.py, and the input ispaper_list.short.csv - The command writes to
./run_demo. It needs internet, a browser for SSRN papers, and an LLM - One file per stage, e.g.,
01-resolve.paper_list.json, and one summary per stage, e.g.,02-download.summary.txt - A past run: 5 of 5 papers resolved, 3 of 5 downloaded, and 3 papers rated
- The runner is
Verification
- The output file is
code_demo.mdin the dir - The five template parts are present, in order
- The command, flags, and input file exist, and the flags appear in
--help - The file says what the demo needs, costs, and how long it takes
- The paths in the file are from the repo root
- Every file the demo makes is in the table, with its content and stage
- The example result comes from a past run's summary files, and says so
- The file has no diagram and no invented command
- No line is over 85 characters outside code blocks and tables
- No file of the dir changed, other than
code_demo.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |