Layered research handover builder

What goes in and out

You give it

• A research question, audience, notes, source evidence, and a destination folder.
• Source text (optional)

You get

• A research index, findings summary, topic analyses, evidence records, and coverage notes.

How the task works

• Know the folder names. 00-index is the map of files. 01-summary is the short findings (layer 1, L1). 02-analysis holds one file per topic (L2). 03-dossiers holds the evidence, such as source excerpts and data (L3).
• Separate the layers. Keep the index for finding files. Put findings in the summary, reasoning in the analysis, and source facts in evidence records.
• Connect findings to evidence. Link each summary to the right analysis files. Link the analysis to the records behind it.
• Check the handover. Check the entry point, paths, and gaps. Make sure each file makes sense on its own. Treat the bundled checker as a helper.

Full instructions

• Before you start, gather: your research question, your notes and source files (text, links, data), who will read the work, and a folder to save into.
• Download the skill folder. In Claude, open Customize → Skills, then choose + → Create skill → Upload a skill. In ChatGPT, add the files to a project's Sources. In Gemini, make a Gem and paste the instructions. Or paste the instructions into a chat. The skill reads four reference files in its folder, so keep the folder together.
• Give your AI your research question, your notes and sources, who will read the work, and a folder to save into.
• Ask your AI to follow this skill. It drafts the one-file summary first, links it to one file per topic, and links each topic file to evidence files (source excerpts, data, method notes). It repeats until no gaps are left.
• Open 00-index.md and the summary first. Click through to a topic file and an evidence file to check the links work and each file makes sense alone.
• Read the coverage notes for gaps. Fill them, then ask your AI to update the links.
• Share the index and the summary with readers first. Send the evidence files only to people who want to check the sources.
• Where this copy comes from. We imported it from magnus919/agent-skills at commit 92c327e. The skill file's own metadata names an earlier home, magnus919/hermes-profiles, by the same author.

Full instruction file

Artifact Pyramids for Agentic AI Research

Progressive disclosure governs how we feed agents context: metadata at startup, instructions on activation, resources on demand. The Artifact Pyramid applies the same principle to what agents produce. Three layers of increasing depth, each independently consumable, each linking down to the next.

Before you start

Use the material below to do this job. If facts or tool access are missing, explain what you can finish and what must wait.

What you need (use your own material or the linked skill):

• Your question (yours): the decision or problem, and what a good outcome looks like.

Makes it better (optional):

• Source text (yours): a long source in full: an article, a video or talk transcript, or notes from a book, with its title, author and link.

How to start:

1. Look first. Use what they've already attached, pasted or put in their about-me note. In a coding assistant with file access, look in the project too for these by name.
2. Check what's missing. Look for your question, source text. They can attach files, paste the details, or share a file path your assistant can read. Ask only for missing facts that change the result. If they ask you to start with what they have, complete the parts you can and mark the gaps.
3. Do the job. Follow the skill below with the facts and tools you have. Mark each gap with MISSING: where it belongs and never invent a fact to fill it.

Tools that do this best:

• A chat AI that can read the bundled reference files: Use the supplied references and templates for the chosen task. Scripts are optional unless that task specifically needs them.

Loading Guidance

When producing an artifact pyramid, load these references as a required set (not piecemeal):

These four define complementary aspects of the spec that the others assume. Loading only a subset risks violating content contracts (e.g., putting findings in 00-index) or skipping required navigation affordances. Load the full set before writing any pyramid files.

The reference table below describes when to load each file; the four above are always required for pyramid production. The remaining references (framework, worked example, canonical article, intellectual lineage, provenance, composite synthesis) are supplementary — load when the task calls for conceptual depth or a worked pattern.

The Pyramid

      ┌──────────────┐
      │  L1 SUMMARY  │  One file: research question, key findings,
      │    🎯        │  most important implications. Links to L2 files.
      └──────┬───────┘
      ┌──────┴───────┐
      │  L2 ANALYSIS │  Per-dimension files: market, competitive,
      │  COLLECTION  │  technical feasibility, risk. Self-contained,
      │   🧩        │  each links to L3 dossiers.
      └──────┬───────┘
      ┌──────┴───────┐
      │  L3 DOSSIERS │  Source excerpts, raw data tables, interview
      │    📦        │  transcripts, methodology notes. Reference
      └──────────────┘  library, pulled on demand.

The pyramid is consumed top-down but produced via recursive gap analysis: start with the summary, embed links to analysis files, write analysis files that link to dossiers, and evaluate after each round whether gaps remain.

Layer numbering is top-down — L1 is the most distilled layer (the entry point), L3 is the most detailed (pulled on demand). This mirrors the Agent Skills input model: metadata (L1) → instructions (L2) → resources (L3).

The Navigation Mechanism

Every file at every layer carries, at the bottom, an explicit SOURCES section with absolute path references and descriptions:

SOURCES (LAYER 2 NAVIGATION)
research/analysis/market-position.md
 -> Competitor mapping and market share analysis supporting Section 2
research/analysis/technical-feasibility.md
 -> Architecture evaluation supporting Section 3
research/dossiers/competitor-profiles.md
 -> Raw competitor data dossiers

These aren't footnotes. They are navigation affordances for agent consumers. Each description answers the question the consuming agent asks before loading: what will I find if I go deeper?

Reference Files

Scripts

Templates

Quick Start

# Scaffold a new research project with all three layer directories
mkdir -p my-project/{01-summary,02-analysis,03-dossiers}
cp assets/pyramid-template.md ./my-project/00-index.md

# Check structural coverage of an existing project
scripts/pyramid-status.sh ./my-project

# Extract candidate atoms from source text
scripts/extract-atoms.py ./my-project/03-dossiers/source-1.txt

Project Structure

my-project/
├── 00-index.md              # Project scaffold (from template)
├── 01-summary/              # L1: one file — key findings, implications, links to L2
├── 02-analysis/             # L2: per-dimension files (market, competitive, technical)
├── 03-dossiers/             # L3: source excerpts, transcripts, raw data, methodology
└── artifact-inventory.md    # Cross-layer tracking (from template)

The numbered prefixes mirror the pyramid's top-to-bottom orientation: 01 is most consumed, 03 is pulled on demand.

Key Principles

1. Progressive disclosure is symmetric. The same three-tier model governs what agents consume (metadata → instructions → resources) and what they produce (summary → analysis → dossiers).
2. Each layer is independently consumable. A product-manager agent reads only the L1 summary. A data-scientist agent reads a single L2 analysis file. A verifier reads L3 dossiers.
3. Navigation is explicit. Every file carries a SOURCES section with absolute paths and descriptions — not footnotes, but agent navigation affordances answering what will I find if I go deeper?
4. Depth varies by mission complexity. A simple brief may produce only L1 + 2 analysis files. A competitive landscape may need all three layers with multiple files per layer.
5. Quality gates are directional. Material moves from L3 (sources) toward L1 (summary) only when it meets the gate for the target layer.
6. 03-dossiers/ is flat — no subdirectories. The dossier layer is a flat reference library. Organize with epoch-prefixed or category-prefixed filenames (epoch-1-validation-edit-3.json), not nested directories. Subdirectories inside 03-dossiers/ violate the flat-file contract and break the SOURCES navigation path.
7. Root-level files are amended; lower-level files are fixed. In multi-epoch or multi-phase systems, 00-index.md, 01-summary/findings.md, and 02-analysis/ trajectory files grow as new data arrives. They are rewritten to reflect the current state. Files in 03-dossiers/ and per-category analysis files below 02-analysis/ are created once and never modified — they represent a fixed point in time.

Validation Script Pitfall

scripts/pyramid-status.sh currently discovers layers by matching file names, not canonical directory names. A compliant tree such as 01-summary/findings.md, 02-analysis/topic.md, and 03-dossiers/source.md can therefore be falsely reported as missing L1/L2 when the nested file names do not themselves match the script's layer patterns. It also reports missing YAML frontmatter as a quality issue even though frontmatter is not required by the layer contracts above. Treat this script as a heuristic only; verify canonical directories, one L1 file, per-dimension L2 files, flat L3 files, final ## SOURCES sections, and link resolution independently.

When NOT to use

• Single-turn Q&A with no research artifacts to preserve
• Tasks producing only ephemeral output (one-off calculations, quick lookups)
• Workflows where the source material IS the final output (no synthesis needed)

Portability

This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format.

After this

When you've handed it back, suggest what they could do next in one short question. It's a suggestion: if they're done, that's fine. Offer these, and say they can type their own:

• The Handover note writer. It takes the document.
• The Analysis assumptions logger. It takes the document. If they pick one and that skill is added here, carry straight on with what you just made. If not, give the link and say what to bring.