tech-article-reproducibility

Original：🇺🇸 English

Translated

Evaluate the reproducibility of technical articles. Dispatch a subagent to simulate a first-time reader reproducing the work locally and list missing information. Use as the final check on a draft before publication.

2installs

Sourcemizchi/skills

Added on2026-05-08

NPX Install

npx skill4agent add mizchi/skills tech-article-reproducibility

SKILL.md Content

View Translation Comparison →

Tech Article Reproducibility

Measure the quality of a technical article from the angle of "can a reader reproduce the same thing on their machine?" This is an independent axis from prose-style evaluation (mizchi-blog-style) or logical evaluation. The premise: the most important thing about a technical article is whether a reader can reproduce it on their own machine.

When to use

Final pre-publication check on a technical article draft
Hands-on articles / tutorial articles
Tool introduction articles / setup articles
Verifying an article that claims "it worked"

When not to use:

Conceptual explainer articles (nothing to reproduce)
Poems / opinion pieces
Self-contained small tidbits

Reproducibility check axes (10 axes)

Score each axis on a 0–2 scale, 20 points total → converted to a 10-point scale.

#	Axis	0 (NG)	1 (partial)	2 (OK)
1	Environment prerequisites stated	No OS / version / required tools listed	Partially listed	Everything listed (OS, lang version, CLI tools)
2	Code completeness	Fragments only, imports/setup omitted	Only the main part	Full, copy-pasteable form that runs
3	Command accuracy	Placeholders left as-is ( `<your-token>` etc. without explanation)	Some placeholders	Runnable as-is
4	Version dependency stated	No mention	Partial	Explicit, e.g. "works on v3.x", "v2 or earlier behaves as X"
5	Full config files included	Excerpts only	Main keys only	Full minimal working config
6	Expected output shown	None	Explained in prose	Actual output / screenshot
7	Handling of errors	Not mentioned	One case touched on	Several major errors + how to handle them
8	Project prerequisites stated	Author-environment assumptions are implicit	Partially stated	Paths / repo structure / existing config all stated
9	Link health	Links broken or require auth	Some require auth	All accessible publicly
10	Author-specific knowledge stated	Helpers / dotfiles assumed implicitly	Partially stated	Fully stated or not required

Evaluation workflow

For evaluating technical articles, use the same subagent dispatch as empirical-prompt-tuning. The difference is that the subagent plays the role of "a first-time reader trying to reproduce the work" rather than "an executor."

Fix the target article
subagent dispatch (template below)
Extract "reproduction sticking points" from the returned evaluation
Add / fix text in the article to address those sticking points
If needed, re-evaluate with a fresh subagent

subagent dispatch template

You are a reader interested in <the article's subject area> but new to <the tech stack>.
You are going to read this article and try to reproduce the same thing in your local environment.

## Target article
<path to the article file>

## Evaluation axes (10 reproducibility axes)
Score each axis 0–2. Refer to the rubric in the `tech-article-reproducibility` skill:
/Users/mz/.claude/skills/tech-article-reproducibility/SKILL.md

1. Environment prerequisites stated
2. Code completeness
3. Command accuracy
4. Version dependency stated
5. Full config files included
6. Expected output shown
7. Handling of errors
8. Project prerequisites stated
9. Link health (actually verify with WebFetch)
10. Author-specific knowledge stated

## Tasks
1. While reading the article, imagine "where would I get stuck if I reproduced this on my own machine?"
2. Score each axis 0–2 with quoted evidence
3. List the top 5 sticking points with line numbers

## Report structure
- Reproducibility score: X/20 (breakdown table)
- Top 5 sticking points: <line number> <quote> → <why it sticks>
- Missing information: list of things that should be added to the article
- Overall verdict: what percentage chance (subjective) do you have of reproducing this after reading the article

How to read the score

18-20: Publishable as a hands-on piece; almost no additional information needed
14-17: Some googling required, but reproducible; okay to publish
10-13: Information outside the article is required to reproduce; revisions recommended
9 or below: Hard to reproduce; rethink the article's premise or position it as something other than a hands-on piece

Pitfalls

The evaluator's background knowledge is too high: if you don't explicitly tell the subagent to play a "beginner role," it will judge "enough information" from an expert's viewpoint. Emphasize "first-time reader" in the prompt
Ignoring link health: links that are alive at publication time can break a year later. Separately check whether reproduction is possible using only live links
Inlining all sample code: reproducibility goes up, but the article bloats. A hybrid approach that combines inline code with a link to the repository is realistic
Reproducibility ≠ prose quality: an article can be highly reproducible yet hard to read. Combine with
```
mizchi-blog-style
```
and similar to measure both axes