New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Researcher

by alecs5am in alecs5am/ralphy

Deep-research workflow for UGC reference material — turns one or more URLs / handles / trend queries into a single cited research report (report.md + sources.json) that a scenarist or art-director…

Apache-2.0Auto-check passedResearch & Science

Install Researcher

skills CLI
$ npx skills add alecs5am/ralphy --skill researcher -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install alecs5am/ralphy researcher --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/alecs5am/ralphy.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/researcher .claude/skills/researcher && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
researcher
GitHub stars
138
Token cost
~1.9k tokens
SKILL.md length
885 words
Files
17 (incl. scripts, references)
Skills in repo
28
Repo updated
First seen
Licence
Apache-2.0

At a glance

Deep-research workflow for UGC reference material — turns one or more URLs / handles / trend queries into a single cited research report (report.md + sources.json) that a scenarist or art-director…

  • Works in 6 steps: Confirm the question. A topic without a… → research start with a slug derived from… → For each URL / handle: research… → …
  • The user drops a URL on TikTok / Reel / Shorts / YouTube / X / Reddit
  • SKILL.md covers Trigger refinements, Hard invariants, What this skill is not and The workflow, plus 6 more sections
  • Runs TypeScript scripts from its folder

What it does

Researcher is an agent skill from alecs5am/ralphy. Deep-research workflow for UGC reference material — turns one or more URLs / handles / trend queries into a single cited research report (report.md + sources.json) that a scenarist or art-director can act on. Aggregates the per-URL ralphy ref chain (yt-dlp pull → frames → transcript → vision → audio-describe → blueprint) and adds a cross-source LLM synthesis pass on top. USE WHEN the user drops a URL on TikTok / Reel / Shorts / YouTube / X / Reddit, mentions an @handle to audit, asks "how do they do X", asks…

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 18 other files, including scripts and reference files (for example `references/playbook.md`, `references/report-schema.md` and `references/research-bootstrap.md`).

It sits in Research & Science, covering Deep research and Influencer and creator marketing. It works with TikTok, Reddit and YouTube. The repository describes itself as: Open-source desktop app for content creation, with an agent runtime and standalone CLI. The licence is Apache-2.0.

When your agent uses it

  • The user drops a URL on TikTok / Reel / Shorts / YouTube / X / Reddit
  • Mentions an @handle to audit
  • Asks how do they do X
  • Asks whats trending in <niche

Example prompts

  • “how do they do X”
  • “s trending in <niche”
  • “research X”
  • “/researcher”

Requirements

  • Node.js

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Confirm the question. A topic without a research question produces a vague report. If the user dropped a URL with no framing, ask one…
  2. research start with a slug derived from the question and a --question flag.
  3. For each URL / handle: research add-source. If the URL is a profile/handle (no direct video), first use ralphy ref scrape-trends or list…
  4. research synthesize once all sources reach analyzed. If any source failed (status: "failed"), surface the error to the user and decide…
  5. Show the markdown report to the user. Surface the question, the Executive Summary, and 3–5 top findings inline. Point at the file path for…
  6. Handoff: the scenarist reads sources.json (specifically keyFindings per source) when writing the scenario. The art-director reads the…

What it can do on your machine

Read from SKILL.md and the folder at commit 8d139f0. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 7 files in scripts/ (TypeScript), which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Researcher loads about 1.9k tokens when it runs, and up to ~14k if it reads all its reference files. Until then it costs about 228 tokens; SKILL.md has 885 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~228
When it runs · the whole SKILL.md, loaded when a task matches
~1.9k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~14k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from alecs5am/ralphy at commit 8d139f0, republished under its Apache-2.0 licence (© alecs5am). 885 words, ~1,940 tokens.

Download SKILL.mdSave it as .claude/skills/researcher/SKILL.md (or your agent's skills folder). This skill also uses 16 other files; get the full folder from GitHub.
name
researcher
description
Deep-research workflow for UGC reference material — turns one or more URLs / handles / trend queries into a single cited research report (report.md + sources.json) that a scenarist or art-director can act on. Aggregates the per-URL `ralphy ref` chain (yt-dlp pull → frames → transcript → vision → audio-describe → blueprint) and adds a cross-source LLM synthesis pass on top. USE WHEN the user drops a URL on TikTok / Reel / Shorts / YouTube / X / Reddit, mentions an `@handle` to audit, asks "how do they do X", asks "what's trending in <niche>", asks for a competitor breakdown, or wants a style report across multiple references. TRIGGER (EN): "research X", "analyze @handle", "break down this TikTok / Reel / Shorts", "how do they do this", "find how X is done", "what's trending in <niche>", "competitor audit", "extract style from <url>". See body for ALSO FIRE / DO NOT FIRE / HARD INVARIANTS.
namespace
user

Trigger refinements

ALSO FIRE if the message contains a URL on tiktok / instagram / youtube / youtu.be / x / twitter / reddit / facebook AND asks anything analytical about it (in any language).

DO NOT FIRE for rendered-mp4 quality checks (that is /evaluator), for raw downloads-only (use ralphy ref pull directly), or once a scenario is already locked and the user wants prompts / assets (handback to scenarist / art-director).

Hard invariants

  • Never ask the user to "send the file" if the URL is on a social platform — WebFetch returns a JS shell on those, but ralphy ref pull (yt-dlp) gets the mp4.
  • All LLM / vision calls route through cli/lib/providers/llm.ts → callLLM() via the CLI. Don't paste raw OpenRouter / yt-dlp code into ad-hoc scripts.

researcher

You take open-ended reference material — URLs, handles, trend queries — and produce a single deep-research document with cited sources. The contract is: the report is the handoff. A scenarist reading report.md should not need to open the source URLs again to write the scenario.

What this skill is not

  • Not a quality checker for rendered mp4s. For "is this video good / find issues" use /evaluator.
  • Not a one-off downloader. For "just give me the mp4 from this URL" use ralphy ref pull <url> directly.
  • Not a scenario writer. The report ends in handoff — the scenarist consumes sources.json and writes from there.

The workflow

Four CLI verbs cover the loop. Don't skip steps — the synthesis step depends on the per-source ref chain having run.

bash
# 1. Start a topic (creates .ralphy/research/<slug>/state.json)
ralphy research start <topic-slug> --question "<the research question>"

# 2. Add each source (full ref chain: pull → frames → transcribe → analyze → audio-describe → blueprint)
ralphy research add-source <url> --topic <slug>

# 3. Cross-source LLM synthesis → report.md + sources.json
ralphy research synthesize <slug>

# 4. Inspect at any time
ralphy research show <slug>
ralphy research list

add-source is idempotent: if a URL was already pulled into .ralphy/references/<refSlug>/, the chain detects the existing artifacts and skips them. Re-running synthesize after adding more sources updates report.md in place.

Useful flags:

  • --meta-only on add-source — only record the URL + yt-dlp metadata, skip the heavy chain (use when the source is text-only or you only need title / author).
  • --frames <n> on add-source — cap sampled frames (default 12). Bump higher for long-form video.
  • --model <id> on synthesize — override the synthesis model (default google/gemini-2.5-flash).

How to read the report

Two files written to .ralphy/research/<slug>/:

  • report.md — narrative deep-research doc. Sections: Executive Summary, Key Findings (with [^N] footnotes), Patterns Across Sources, Actionable Recommendations (split for scenarist / art-director), Open Questions, Sources. Show this one to the user.
  • sources.json — machine contract for downstream skills. Each source has id (footnote), url, title, refSlug (pointing at raw artifacts in .ralphy/references/<refSlug>/), blueprintPath, and keyFindings[] (3–8 short bullets distilled by the synthesis step). Schema: references/report-schema.md.

The report cites every claim. If the model produces an uncited bullet, the synthesis is suspect — re-run with a different model or check that all sources reached status: "analyzed" via ralphy research show.

When to keep the playbook in mind

.agents/skills/researcher/references/playbook.md is the tool-deep-dive companion. Read it when:

  • The source URL needs a non-standard pull (Playwright for JS-heavy landing pages, manual yt-dlp flags for region-locked content) — see .agents/skills/researcher/references/yt-dlp.md and site-extract.md.
  • The user asks for trend discovery, not a fixed source list — discover-trends sub-task uses ralphy ref scrape-trends to find hashtag candidates, then loops them through add-source.
  • The user wants viral-moment extraction from a long-form video — that is a different sub-task with its own sub-doc (viral-moments.md); the topic-level synthesis here is not the right fit.

This skill is the workflow contract. The playbook is the tool encyclopedia. Don't duplicate; cross-reference.

Show full SKILL.md (353 more words)Show less

Workflow

  1. Confirm the question. A topic without a research question produces a vague report. If the user dropped a URL with no framing, ask one short clarifying question ("what are you trying to learn from this?") before starting.
  2. research start with a slug derived from the question and a --question flag.
  3. For each URL / handle: research add-source. If the URL is a profile/handle (no direct video), first use ralphy ref scrape-trends or list the top videos and add them one by one. Stop adding sources at 6–8 — diminishing returns and the synthesis context fills up.
  4. research synthesize once all sources reach analyzed. If any source failed (status: "failed"), surface the error to the user and decide whether to retry or skip.
  5. Show the markdown report to the user. Surface the question, the Executive Summary, and 3–5 top findings inline. Point at the file path for the full read.
  6. Handoff: the scenarist reads sources.json (specifically keyFindings per source) when writing the scenario. The art-director reads the Patterns Across Sources section when picking prompt seeds and model choices.

When to fall back to the per-source ref chain

If the user only cares about one source (single TikTok, single Reel) and doesn't need a topic-level narrative, the per-source ref chain alone is enough — ralphy ref pull <url> then ralphy ref blueprint <slug> gives a single-source blueprint.md. Use this skill only when there are ≥2 sources or the user explicitly wants a cited report.

Handoff to a fixer / scenarist agent

When the user says "now write the scenario" or similar, a downstream agent reads sources.json and report.md. The minimum it needs from you:

  • Path to report.md
  • Path to sources.json
  • Topic slug (the dir name)
  • Optional: which sources to weight more heavily (when one is a much stronger reference than the others)

Do not paraphrase the findings in chat — the report exists so chat doesn't have to.

References

  • references/report-schema.md — full schema of sources.json + section spec for report.md
  • .agents/skills/researcher/references/playbook.md — tool-deep-dive: yt-dlp flags, Playwright for JS-rendered sites, scrape-trends, viral-moments sub-task
  • cli/lib/research-topic.ts — source-of-truth for the topic state machine
  • MODELS.md — synthesis model defaults (google/gemini-2.5-flash via OpenRouter)

© alecs5am, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 16 other files (scripts, references) in .agents/skills/researcher of alecs5am/ralphy.

  • SKILL.md
  • references/playbook.md
  • references/report-schema.md
  • references/research-bootstrap.md
  • references/site-extract.md
  • references/site-grounding.md
  • references/social-extract.md
  • references/transcript.md
  • references/viral-moments.md
  • references/yt-dlp.md
  • scripts/analyze-video.ts
  • scripts/cross-analyze.ts
  • scripts/extract-design.ts
  • scripts/extract-playdate-gamelist.ts
  • scripts/extract-playdate-sections.ts
  • scripts/find-viral-moments.ts
  • scripts/scrape-tiktok-trends.ts

Open the folder on GitHubat commit 8d139f0

Compare with similar skills

Researcher next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Researcher compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Researcher this skillalecs5am/ralphy138—~1.9kAutomated safety check: PassApache-2.0
Last30daysmvanhorn/last30days-skill64k—~7.9kAutomated safety check: NotesMIT
Influencer Discoverytigerless-labs/influencer-discovery212—~2.5kAutomated safety check: NotesNone
Ray Trend Searchimraywang/rayskills159—~2.1kAutomated safety check: PassCustom licence
Google Social Media Finderbrowser-act/skills6.1k—~1.7kAutomated safety check: PassMIT
Deep Researchcoreyhaines31/makerskills851—~1.4kAutomated safety check: PassMIT

Similar skills

  • Last30days

    mvanhorn/last30days-skill

    Research what people actually say about any topic in the last 30 days.

    64k GitHub stars~7.9k tokensUpdated yesterday
    Research & ScienceAuto-check: notes

  • Influencer Discovery

    tigerless-labs/influencer-discovery

    Find the bloggers/creators who can help promote your work, capture their contact info, and append them to the target sheet in Google Sheets.

    212 GitHub stars~2.5k tokensUpdated 18 days ago
    Marketing & SEOAuto-check: notes

  • Ray Trend Search

    imraywang/rayskills

    Researches what people are saying about a topic over a recent window across X, Reddit, YouTube and the public web, reporting each source's status with links.

    159 GitHub stars~2.1k tokensUpdated 17 days ago
    Research & ScienceAuto-check passed

  • Google Social Media Finder

    browser-act/skills

    Searches Google to discover social media profiles associated with a person, brand, or username; returns platform name, profile URL, username, bio snippet, and follower count across X, Instagram…

    6.1k GitHub stars~1.7k tokensUpdated 1 mo ago
    Marketing & SEOAuto-check passed

  • Deep Research

    coreyhaines31/makerskills

    When you want multi-source, multi-step research on a topic — competitor research before a sales call, market research for a new business idea, positioning angles, due diligence on a partnership or…

    851 GitHub stars~1.4k tokensUpdated 2 days ago
    Research & ScienceAuto-check passed

  • Agent Reach

    Panniantong/Agent-Reach

    Routes web research and platform lookups across 16 sites, including Twitter, Reddit, YouTube, Bilibili, Xiaohongshu and GitHub, through one command-line tool.

    95k GitHub stars~1.4k tokensUpdated 2 days ago
    Productivity & AutomationAuto-check passed

More from alecs5am/ralphy

All 28 skills in this repo

  • Gsap

    alecs5am/ralphy

    GSAP animation reference for HyperFrames. An agent skill from alecs5am/ralphy.

    138 GitHub stars~2.4k tokensUpdated 18 days ago
    Auto-check passed

  • Editor

    alecs5am/ralphy

    Composition and render craft — assembles scenario.json plus asset-manifest.json into a HyperFrames HTML composition and renders the mp4.

    138 GitHub stars~3.6k tokensUpdated 18 days ago
    Auto-check passed

  • Evaluator

    alecs5am/ralphy

    Quality evaluation of rendered UGC mp4s — scene segmentation, audio loudness / dead-air, caption density, and per-scene visual analysis.

    138 GitHub stars~3.6k tokensUpdated 18 days ago
    Auto-check passed

  • Producer

    alecs5am/ralphy

    End-to-end orchestration — the wrapper that drives the whole production contract across roles, plus batch production.

    138 GitHub stars~4.7k tokensUpdated 18 days ago
    Auto-check passed

  • Scenarist

    alecs5am/ralphy

    Scenario and script craft — writes and reworks the scene-by-scene scenario.json: hook, beat structure, per-scene VO, on-screen text, pacing, and the language/aspect pre-flight.

    138 GitHub stars~3.2k tokensUpdated 18 days ago
    Auto-check passed

  • Troubleshooting

    alecs5am/ralphy

    Ralphy CLI operations and repair — environment setup, API keys and connectors, ralphy doctor, reading logs, diagnosing a failed generation or render, and the CLI cookbook for verbs other roles call.

    138 GitHub stars~1.4k tokensUpdated 18 days ago
    Auto-check passed

Works with

Categories

Questions about Researcher

What does Researcher do?

Deep-research workflow for UGC reference material — turns one or more URLs / handles / trend queries into a single cited research report (report.md + sources.json) that a scenarist or art-director…. Researcher is an agent skill from alecs5am/ralphy.json) that a scenarist or art-director can act on.

When should I use Researcher?

Researcher fits situations like: the user drops a URL on TikTok / Reel / Shorts / YouTube / X / Reddit; mentions an @handle to audit; asks how do they do X; asks whats trending in <niche.

How do I install Researcher in Claude Code?

Run `npx skills add alecs5am/ralphy --skill researcher -a claude-code`. Or copy the skill folder (.agents/skills/researcher in alecs5am/ralphy) into .claude/skills/researcher in your project. Claude Code loads it when a task matches its description.

How do I install Researcher in Codex?

Run `npx skills add alecs5am/ralphy --skill researcher -a codex`. Or copy the skill folder (.agents/skills/researcher in alecs5am/ralphy) into .agents/skills/researcher in your project. Codex loads it when a task matches its description.

Can I use Researcher in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add alecs5am/ralphy --skill researcher -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/researcher, .gemini/skills/researcher, .github/skills/researcher and .opencode/skills/researcher in your project.

What does Researcher need to run?

Going by SKILL.md and its folder, Researcher needs TypeScript for the scripts in its folder. Our summary lists: Node.js.

Does Researcher access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Researcher safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Researcher use?

Researcher is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Researcher use?

About 1.9k tokens (SKILL.md is roughly 7.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 12k tokens, read only when the agent opens those files.

What are the alternatives to Researcher?

Skills that share tags, products or a category with Researcher: Last30days (mvanhorn/last30days-skill, 64k stars), Influencer Discovery (tigerless-labs/influencer-discovery, 212 stars), Ray Trend Search (imraywang/rayskills, 159 stars) and Google Social Media Finder (browser-act/skills, 6.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Researcher?

alecs5am (a GitHub user) maintains it in alecs5am/ralphy, which has 138 GitHub stars. The repository holds 28 skills in this directory. The repository was last updated on September 22, 2026.

Source: alecs5am/ralphy on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.