agentleFS
Sign inStart free
arndvsarndvs/ctrlshft/skills/research/SKILL.md

research

Skill0 starsChanged 6 months agoMITView on GitHub

Cache expensive exploration into a research document before building. Use when asked to 'research', 'investigate before building', 'gather context', 'flush unknowns', or before a large feature where unknowns need flushing.

We split this skill into the rules it gives an agent

16 rules. 0 are common, 11 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 165 edited versions we read keep these.

  • 11

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

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

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

    If running interactively (human present), output "Read Research skill." to acknowledge.

    line 8
  2. Distinctive:

    Before a large feature where architecture, dependencies, or API choices are unclear

    line 14
  3. Distinctive:

    When multiple conversations will work on the same area

    line 15
  4. Distinctive:

    When exploration would consume >20% of context and you still need room to implement

    line 16
  5. Distinctive:

    When the user says "research this first" or "investigate before building"

    line 17
  6. Very specific:

    If working/research/<topic>.md already exists:

    line 23
  7. Very specific:

    Check the Generated date in the header

    line 26
  8. Distinctive:

    If <7 days old and topic matches: use it as-is, skip to handoff

    line 27
  9. Distinctive:

    If >7 days old or topic doesn't match: re-validate by spot-checking 2-3 key claims, then update or regenerate

    line 28
  10. Distinctive:

    After research is complete, offer the user three paths:

    line 75
  11. Distinctive:

    When passing to a new conversation, always include the research file in @-references

    line 84
  12. Very specific:

    If a working/active/<topic>.md plan exists, the pickup command should include both: @working/research/<topic>.md @working/active/<topic>.md …

    line 85
  13. Distinctive:

    If the research file is >7 days old, re-validate before relying on it

    line 86
  14. Distinctive:

    If the codebase has changed significantly (major refactor, new dependencies), regenerate

    line 87
  15. Distinctive:

    Delete research files after the feature ships — they're working documents, not permanent docs

    line 88
  16. Very specific:

    If the synthesis has lasting value beyond the immediate task, promote it to docs/research/<topic>.md before deleting the working copy

    line 89

“Common” is measured: kept by at least 6 in 10 of the 165 edited versions of this file we could read. “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

If running interactively (human present), output "Read Research skill." to acknowledge. If running with --dangerously-skip-permissions (AFK/unattended), skip acknowledgement and proceed directly.

Cache expensive exploration into a persistent working/research/<topic>.md so implementation conversations can start with full context instead of re-exploring.

When to Use

  • Before a large feature where architecture, dependencies, or API choices are unclear
  • When multiple conversations will work on the same area
  • When exploration would consume >20% of context and you still need room to implement
  • When the user says "research this first" or "investigate before building"

Process

1. Check for Existing Research

If working/research/<topic>.md already exists:

  • Read it fully
  • Check the Generated date in the header
  • If <7 days old and topic matches: use it as-is, skip to handoff
  • If >7 days old or topic doesn't match: re-validate by spot-checking 2-3 key claims, then update or regenerate

2. Decompose

Break the research topic into 3-6 distinct areas of concern. Each area should be explorable independently.

3. Parallel Exploration

Spawn a dedicated sub-agent for each area using the explore verb (per the explore skill). Each sub-agent should have a narrow, specific focus.

4. Synthesize

Combine all sub-agent findings into working/research/<topic>.md with this structure:

# Research: [Topic]

Generated: [date]
Topic: [one-line summary]

## Summary

[2-3 paragraph executive summary of findings]

## Architecture

[Relevant code paths, data flow, existing patterns]

## Constraints

[Technical limitations, API quirks, performance bounds, compatibility issues]

## Dependencies

[External services, libraries, APIs involved and their current state]

## Open Questions

[Unresolved decisions that need human input]

## Recommendations

[Concrete next steps based on findings]

5. Handoff

After research is complete, offer the user three paths:

  1. /write-a-prd — capture findings as a formal PRD
  2. /do-work — start implementing with working/research/<topic>.md as context
  3. Continue exploring — spawn additional sub-agents for open questions

Lifecycle Management

  • Research lives in working/research/<topic>.md — one file per topic
  • When passing to a new conversation, always include the research file in @-references
  • If a working/active/<topic>.md plan exists, the pickup command should include both: @working/research/<topic>.md @working/active/<topic>.md — pick up on remaining slices. Start with Slice [N].
  • If the research file is >7 days old, re-validate before relying on it
  • If the codebase has changed significantly (major refactor, new dependencies), regenerate
  • Delete research files after the feature ships — they're working documents, not permanent docs
  • If the synthesis has lasting value beyond the immediate task, promote it to docs/research/<topic>.md before deleting the working copy
  • See docs/ARTIFACT-LIFECYCLE.md for the full lifecycle

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.

Reviews can't be read right now.

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.

Check your setup, free