agentleFS
KcAnomKcAnom/pi-fairy-tales-chains/skills/research-gather/SKILL.md

research-gather

Skill0 starsChanged 4 months agoMITView on GitHub

Phase 1 of 3 in the research chain (gather → synthesize → artifact). Collects raw material from user-provided sources — URLs, local docs, or topics — using the fetch tool (SSRF-safe) for remote content and explore-role subagents for local docs and broad exploration. This phase starts the durable chain run (state tracked by the chain tool). Trigger whenever the user wants to start a research run: "research-gather", "start a research chain", "phase 1 of research", "research this topic", "gather sources on X", or standalone "research".

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All chain state is managed by the chain tool: authoritative JSON at .pi/fairy-tales/chains/research/state.json with a human-readable …

    line 29
  2. Very specific:

    Call the chain tool with action: "status", chain: "research":

    line 38
  3. Very specific:

    If an active run exists, a research run is already mid-flight (the status shows its current phase — a legacy .research-state.md from an …

    line 40
  4. Very specific:

    If the tool reports the chain is locked by another session, abort and tell the user.

    line 45
  5. Very specific:

    If there is no run, or the last run is complete/abandoned, start fresh: action: "start", chain: "research", task: "<research question / …

    line 47
  6. Very specific:

    If a returned quest is already done (crash-resume case), reuse its stored result.

    line 78
  7. Distinctive:

    Call the chain tool:

    line 94
  8. Distinctive:

    After completing this phase, output exactly:

    line 112
  9. Distinctive:

    Do not start the next phase.

    line 117

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Research: Gather

Chain version: 2 (durable state contract — see docs/STATE-CONTRACT.md)

Phase 1 of 3: research-gather → research-synthesize → research-artifact

Overview

Entry point of the research chain. Takes the user's research question plus any provided sources (URLs, local file/doc paths, or topics to explore) and collects raw material: per-source notes, key quotes, and links.

Fetches remote content with the fetch tool (SSRF-safe) and dispatches explore-role subagents to read local docs and codebase material, so the gather pass covers both "on the web" and "already on disk" sources in parallel.

All chain state is managed by the chain tool: authoritative JSON at .pi/fairy-tales/chains/research/state.json with a human-readable state.md projection beside it. Never create or edit state files by hand, and never create lock files — the tool locks for you.

Workflow

Step 1 — Start the run (entry phase)

Call the chain tool with action: "status", chain: "research":

  • If an active run exists, a research run is already mid-flight (the status shows its current phase — a legacy .research-state.md from an older version is imported automatically). Show the user the status and ask whether to resume from the current phase (run that phase's skill) or discard it (action: "abandon") and start over. Do not silently overwrite.
  • If the tool reports the chain is locked by another session, abort and tell the user; a dead session's lock can be cleared with action: "unlock".
  • If there is no run, or the last run is complete/abandoned, start fresh: action: "start", chain: "research", task: "<research question / topic>". Note the runId in the response — it keys this run's quest dedupe keys.

Step 2 — Identify sources

Clarify the research question and enumerate the sources to cover: explicit URLs the user gave, local doc/codebase paths, and any topics that need open-ended discovery.

Step 3 — Fetch remote sources

For each URL, use the fetch tool (SSRF-safe) to retrieve the content — it blocks requests to private/internal/link-local IP ranges and unsafe redirect targets, so it is the correct way to pull content from user-supplied or untrusted URLs. Never fetch external URLs any other way in this phase.

Step 4 — Explore local material via durable quests

For local docs, codebases, or open-ended topics that need discovery rather than a direct URL, dispatch explore-role subagents — one per source cluster or research sub-question. Because this exploration can be long-running and must survive a session restart, use the quest tool rather than a bare agent call:

  • quest action enqueue with role: "explore", a self-contained task (the source cluster or sub-question, and what to report back), and:
    • dedupeKey: "research/<runId>/gather/<cluster>" (a descriptive id for the source cluster/sub-question) — re-running a crashed phase returns the same quest instead of duplicating exploration;
    • chain: { chain: "research", runId: "<runId>", phase: "gather" };
    • retainUntilConsumed: true.
  • Issue independent clusters' enqueue calls in one message so they run in parallel.
  • If a returned quest is already done (crash-resume case), reuse its stored result; otherwise quest action run with its id and collect the result. After extracting what's needed into chain state (Step 6), quest action consume each quest by id.

Step 5 — Capture per-source notes

For every source (remote or local), record:

  • Source name/URL/path
  • A short summary of what it says
  • Key quotes, captured verbatim with attribution
  • Any links or citations found within it worth following up

Step 6 — Complete the phase

Call the chain tool:

action: "complete-phase", chain: "research", phase: "gather",
summary: "raw material gathered from N sources (M remote via fetch tool, K local via explore quests); scope chosen, sources skipped and why",
data: {
  "sources": [
    { "source": "<name/URL/path>", "summary": "<short summary>", "quotes": ["<quote>", "..."], "links": ["<link>", "..."] }
  ]
},
artifacts: { "exploreQuests": "<quest ids>" }

The tool validates this is the current phase, advances the run to synthesize, and rewrites the JSON + markdown projection atomically.

Handoff

After completing this phase, output exactly:

Phase 1 complete. Chain state updated (.pi/fairy-tales/chains/research/state.json). Run /research-synthesize to begin Phase 2.

Do not start the next phase. Do not offer to continue. Output only the handoff line and stop.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.