nature-story — Claude Code skill: build evidence-grounded story architecture
nature-story — a skill that transforms raw research ideas into rigorous scientific narratives with competing hypotheses, literature benchmarks, and figure-driven paper plans.
MIT ★ 240 updated 2026-09-18
npx skills add franklee16/academic-research-skills --skill nature-story -a claude-codeWhat nature-story does
nature-story constructs the scientific argument before language polishing. It separates what you've already observed and measured from assumptions and desired outcomes—then helps identify a weightier question your evidence can genuinely answer.
The skill offers multiple paths: lift a raw concept into competing story candidates, audit an existing draft outline, find literature precedents, architect a figure sequence, or validate user-provided concepts against disciplinary knowledge. Each route draws on reference guides for literature search, knowledge validation, story archetypes and output standards.
It's built for engineering and coupled human–environment systems: atmosphere, air pollution, energy, cities, infrastructure, behavior, economics and policy. It is not a substitute for domain modelling, statistical identification, systematic review, or manuscript polish.
What it helps with
- elevate a preliminary finding into competing scientific narratives
- diagnose weaknesses in an existing analysis and identify what's missing
- find literature precedents and carve out differentiation space
- sequence figures so each one shifts what the reader believes
- distinguish observed facts from untested mechanisms and desired outcomes
Example prompts for the agent
- I have early results on how air pollution affects commute behavior. Generate competing story architectures.
- Review my draft paper outline on energy transitions in cities. Where's the argument weakest?
- What are the closest precedents in Nature or Science on infrastructure adaptation? How do those papers construct their central claim?
How to install nature-story
1Skills CLI (Vercel)
npx skills add franklee16/academic-research-skills --skill nature-story -a claude-code2Manually: put the files in place
~/.claude/skills/nature-story-main/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/nature-story-main/
1Skills CLI (Vercel)
npx skills add franklee16/academic-research-skills --skill nature-story -a codex2Manually: put the files in place
.agents/skills/nature-story-main/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add franklee16/academic-research-skills --skill nature-story -a cursor2Manually: put the files in place
.cursor/skills/nature-story-main/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install franklee16/academic-research-skills paper-writing/nature-story-main/SKILL.md2Manually: put the files in place
.github/skills/nature-story-main/SKILL.md1Skills CLI (Vercel)
npx skills add franklee16/academic-research-skills --skill nature-story -a gemini-cli2Platform CLI
gemini skills install https://github.com/franklee16/academic-research-skills --path paper-writing/nature-story-mainManually: put the files in place
.devin/skills/nature-story-main/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about nature-story
How do I install nature-story in Claude Code?
Run npx skills add franklee16/academic-research-skills --skill nature-story-main -a claude-code, then open ~/.claude/skills/nature-story-main/SKILL.md.
What does nature-story do?
It structures scientific narratives: separates confirmed results from assumptions, generates competing hypotheses, identifies literature benchmarks, and plans how to sequence figures so each changes reader understanding.
Which research areas is nature-story designed for?
Atmospheric science, air pollution, energy, urban systems, infrastructure, human behavior, economics and policy—especially when you need literature models, conceptual reframing or a figure plan, not final prose editing.
Source text
SKILL.md · MIT
--- name: nature-story description: Turn early engineering research ideas into evidence-grounded, general-interest scientific story architectures. Use for atmospheric science, air pollution, energy, cities, infrastructure, human behaviour, socioeconomic systems, and policy when the user needs literature analogues, conceptual reframing, competing storylines, missing analyses, or a figure-led paper plan—not final prose polishing. --- # Nature Story Build the scientific argument before polishing the language. The goal is not to make an ordinary idea sound important; it is to identify a more consequential question that the evidence could genuinely answer. ## Scope and boundary Use this skill for engineering and coupled human–environment systems, especially atmosphere, air pollution, energy, cities, infrastructure, behaviour, economics, inequality, development, and policy. Interdisciplinary combinations are welcome when the causal chain is explicit. Do not use it as a substitute for domain modelling, statistical identification, systematic review, manuscript polishing, or journal acceptance prediction. Do not claim that a framing is “Nature-level” merely because it contains novelty language. Journal fit is an uncertain editorial judgement. ## Route the task - **Idea uplift**: raw topic or preliminary result → competing scientific stories and research programme. - **Story audit**: existing analyses or draft outline → diagnose the current story, weakest link, deletions, and upgrades. - **Literature-led architecture**: topic → nearest high-impact papers, transferable story moves, and differentiation space. - **Figure architecture**: established claims → figure sequence in which each figure changes what the reader believes. - **Knowledge audit**: user-provided concepts, mechanisms, references, or interpretations → independent disciplinary verification before story construction. For every route, read [references/literature-workflow.md](references/literature-workflow.md) and [references/knowledge-validation.md](references/knowledge-validation.md). Read [references/story-archetypes.md](references/story-archetypes.md) when generating candidate stories, [references/domain-lenses.md](references/domain-lenses.md) when selecting mechanisms and consequences, and [references/output-contract.md](references/output-contract.md) before delivering the full architecture. Use [references/illustrative-anchors.md](references/illustrative-anchors.md) only for examples of transferable story moves; never treat it as the live literature search. ## Core workflow ### 1. Separate what exists from what is hoped Extract five ledgers from the user's material: 1. **Observed or computed** — results already supported. 2. **Designed** — data, models, experiments, comparisons, or policies actually evaluated. 3. **Inferred** — interpretations that require a stated bridge. 4. **Assumed** — untested mechanisms, causal directions, baselines, or future conditions. 5. **Wanted** — desired significance, journal, audience, or policy relevance. Never silently promote an item from assumed or wanted into observed. ### 2. Audit user-provided knowledge Treat user-provided papers, concepts, mechanisms, numerical values, causal stories, and writing advice as **provisional inputs**, not authoritative facts. The user may be correct, partly correct, outdated, oversimplified, or wrong. Before adopting the user's framing: - decompose it into checkable claims; - independently learn the relevant disciplinary definitions, mechanisms, evidence standards, and active debates; - search primary literature and authoritative sources that both support and challenge the claims; - distinguish factual disagreement from alternative terminology, scope, scale, or normative preference; - correct, bound, or reject unsupported claims with evidence and respectful explanation; - preserve useful insights without inheriting their assumptions. Do not let polished writing advice override the field's scientific logic. A storytelling pattern is transferable only when it fits the system, mechanism, and available evidence. Follow [references/knowledge-validation.md](references/knowledge-validation.md). ### 3. Search before architecting Find recent and seminal near-neighbour papers before recommending a story. Search three neighbourhoods: - **Topic neighbours**: same system, intervention, hazard, technology, population, or outcome. - **Mechanism neighbours**: same threshold, feedback, behavioural response, spatial transfer, distributional process, lock-in, or compound interaction—even in another application. - **Narrative neighbours**: papers whose central move resembles the candidate story, such as overturning a stationary assumption or exposing a policy trade-off. Prioritize research articles in Nature, Science, and their relevant research journals, then add the strongest field-journal papers needed to establish novelty. Verify bibliographic metadata and distinguish direct access from abstract-only interpretation. Return a compact reference matrix before using the papers as models. Follow [references/literature-workflow.md](references/literature-workflow.md). ### 4. Distil the scientific tension Express the project independently of methods: - **System**: what coupled system is changing? - **Default belief or decision rule**: what is normally assumed, optimized, averaged, or ignored? - **Tension**: why might that belief fail? - **Phenomenon**: what pattern, response, or inconsistency is visible? - **Mechanism**: what process could produce it? - **Consequence**: what changes for understanding, design, governance, welfare, or risk? - **Boundary**: where should the claim stop? If the tension is only “this has not been mapped before”, label the current contribution as descriptive or quantification-led. ### 5. Generate genuinely different candidates Produce at least three, normally four to six, candidate stories. Include: - a **conservative** version supportable with current evidence; - a **mechanism-first** version; - a **consequence-first** or decision-first version; - one **high-upside/high-risk** version that clearly states what new evidence it requires. Select archetypes because the system supports them, not because the labels sound fashionable. Consider trade-offs, rebound, thresholds, spillovers, sign reversals, unequal burdens, compound risks, non-stationarity, bottleneck relocation, policy-mix non-additivity, and hidden dependencies only when a plausible pathway and discriminating test exist. See [references/story-archetypes.md](references/story-archetypes.md). For each candidate give: central question, expectation challenged, one-sentence spine, causal chain, decisive evidence, competing explanation, fatal weakness, required new work, and credible target audience. ### 6. Stress-test before ranking Score each candidate from 1–5 on: - conceptual novelty rather than “first application”; - generality and transferability; - mechanism and causal identification; - magnitude and practical materiality; - surprise relative to a documented expectation; - consequence for theory, design, behaviour, or policy; - robustness to alternative specifications and boundary choices; - feasibility with available data, time, and methods; - ethical and distributional completeness; - narrative economy: every major analysis advances the same claim chain. Show the rationale, uncertainty, and **weakest link**. Do not average away a fatal zero: a story that requires unavailable causal evidence or contradicts the data must be downgraded. ### 7. Turn the winner into a research programme For the leading two or three candidates, specify: - minimum publishable evidence; - essential mechanism or identification test; - robustness and falsification tests; - boundary/heterogeneity analysis; - decision, exposure, or welfare consequence; - one “killer analysis” with the highest information gain; - analyses to move to Supplementary Information; - analyses to delete because they do not change the argument; - dependencies, data gaps, and stop/go criteria. Distinguish **essential**, **strong enhancer**, and **optional** work. Prefer an analysis that discriminates between explanations over another descriptive map, scenario, subgroup, or model ensemble. ### 8. Build a figure-driven argument Design figures as questions and claim transitions, not containers for available outputs. A common sequence is: 1. establish the phenomenon or resource; 2. create the tension or reveal the failure of the default belief; 3. identify the mechanism or causal response; 4. demonstrate boundary, heterogeneity, or competing explanation; 5. show consequence, intervention, or decision change. For each figure state: reader question, central claim, necessary analysis, comparison/counterfactual, uncertainty display, and the belief change created by the figure. Keep comparable panels on consistent scales and use physically meaningful, perceptually uniform, colourblind-friendly palettes. ### 9. Convert the argument into Results section titles For the recommended story, always provide a manuscript-ready Results architecture containing **exactly four or five section titles**. The titles must form a causal or inferential progression rather than a list of methods, datasets, places, or figures. They should normally move from phenomenon to tension, mechanism, boundary or heterogeneity, and consequence or decision relevance, while adapting that sequence to the actual evidence. For each proposed Results section provide: - a concise, claim-led title in the manuscript's language; - the question answered and the claim advanced; - the main figure or decisive analysis it maps to; - the evidence status: supported now, requires analysis, or conditional on a stated result; - the transition explaining why the next section follows. Do not invent a finding merely to make a title sound definitive. When results are preliminary or absent, use honest prospective wording and explicitly mark the title as provisional. Avoid generic headings such as “Spatial analysis”, “Model results”, “Case study”, or “Policy implications” unless the user specifically requests descriptive headings. ### 10. Calibrate claims Tag every major claim as **descriptive**, **associational**, **causal**, **mechanistic**, **projective**, **normative**, or **decision-analytic**. Require evidence appropriate to the tag. In particular: - causal language needs a credible identification strategy or intervention; - modelled mechanisms need perturbation, attribution, or competing-model tests; - projections need scenario and structural uncertainty; - policy recommendations need objectives, affected groups, trade-offs, and institutional constraints; - behavioural rebound needs an observed or modelled response pathway, not a rhetorical label. ## Non-negotiable rules - Never fabricate papers, quotations, journal fit, effect sizes, mechanisms, or user results. - Never accept a user's scientific claim merely because it is stated confidently, repeated, or embedded in polished prose. - Never equate high citation, journal prestige, or recency with evidential quality. - Never copy a paper's wording or story wholesale; extract the move, then state how the new project differs. - Never manufacture surprise. Name the prior expectation and evidence for it. - Never hide an inconvenient trade-off, subgroup, spatial transfer, time-scale reversal, or null result that changes the central interpretation. - Prefer a narrower supportable story over a broad speculative one. - Ask at most a few questions when missing information would materially change the architecture; otherwise proceed with explicit assumptions. ## Delivery Use the full contract in [references/output-contract.md](references/output-contract.md). Lead with the literature reference matrix and the best-supported recommendation, then present competing versions. Always include the four- or five-section Results title architecture for the recommended story. End with a concrete next-analysis decision and the information that would make you change your recommendation.
© franklee16 · MIT · franklee16/academic-research-skills