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

File Retrieval

by THU-SAGE in THU-SAGE/syll

Finds a file on the local machine, shows previews of the candidates, and sends the one you pick back through the current chat channel after confirmation.

MITAuto-check passedProductivity & Automation

Install File Retrieval

skills CLI
$ npx skills add THU-SAGE/syll --skill file-retrieval -a claude-code

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

GitHub CLI
$ gh skill install THU-SAGE/syll file-retrieval --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/THU-SAGE/syll.git skills-src && mkdir -p .claude/skills && cp -r skills-src/syll/skills/file-retrieval .claude/skills/file-retrieval && 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
file-retrieval
GitHub stars
303
Token cost
~1.3k tokens
SKILL.md length
653 words
Files
1
Skills in repo
8
Repo updated
First seen
Licence
MIT

At a glance

Finds a file on the local machine, shows previews of the candidates, and sends the one you pick back through the current chat channel after confirmation.

  • Works in 7 steps: Send a short message announcing the… → Call find_file(query=..., root=...,… → Branch on the result count → …
  • Asked to find a file on the user's computer and send it
  • SKILL.md covers Procedure, Worked Example (English), Worked Example (Chinese) and Rules (do not break these)
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

The skill uses three tools, `find_file`, `file_preview` and `attach_file`, across two separate turns. In the first turn the agent announces the search and calls `find_file` with a query, a search root such as the desktop, documents, downloads or home folder, and file extensions when the type is known, then branches on the number of hits. With none it asks for another keyword or root, with one it still previews and asks, and with more than five it previews only the top five by modification time.

It renders previews in one call and replies with a numbered list showing filename, size, modification time and the full absolute path in the reply text, because the next turn keeps only the previous assistant text and not tool arguments. It stops there. In the second turn it resolves your choice against that list, asks again if the choice is ambiguous, and only then calls `attach_file` with the path and confirms that the file is on its way.

When your agent uses it

  • Asked to find a file on the user's computer and send it
  • Locating a presentation or PDF on the desktop or in Downloads
  • Choosing between several similarly named files by preview

Example prompts

  • “Find the weekly report pptx on my desktop and send it to me.”
  • “Grab the latest invoice PDF from my Downloads folder.”
  • “I need the budget spreadsheet from Documents, so show me what you find first.”

Requirements

  • Agent tools named `find_file`, `file_preview` and `attach_file`
  • A chat channel that can deliver file attachments

Workflow steps

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

  1. Send a short message announcing the search. Example: "going to check the desktop now" / "looking for it now".
  2. Call find_file(query=..., root=..., extensions=[...]). Pick root based on what the user said (default ~/Desktop if unspecified and the…
  3. Branch on the result count
  4. Send a message announcing the preview step. Example: "found N, rendering thumbnails so you can pick".
  5. Call file_preview(paths=[...]) with all candidate paths in one call.
  6. Produce the final reply for this turn. It must contain
  7. Stop this turn. Do not call attach_file yet.

What it can do on your machine

Read from SKILL.md and the folder at commit 3741347. 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

    No scripts in the folder and no shell commands in SKILL.md.

    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

File Retrieval loads about 1.3k tokens when it runs. Until then it costs about 44 tokens; SKILL.md has 653 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~44
When it runs · the whole SKILL.md, loaded when a task matches
~1.3k

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); files beside SKILL.md are not scanned.

SKILL.md

The full file from THU-SAGE/syll at commit 3741347, republished under its MIT licence (© THU-SAGE). 653 words, ~1,291 tokens.

Download SKILL.mdSave it as .claude/skills/file-retrieval/SKILL.md (or your agent's skills folder).
name
file-retrieval
description
Find a file on the local filesystem, show previews, and send it to the user after confirmation. Use when the user asks to find, locate, retrieve, or send a file.

File Retrieval

Use this skill when the user asks you to find a file on the local machine and deliver it through the current channel. Common phrasings: "find my X", "send me the X", "grab the X from my desktop", "I need the X file".

This skill uses three tools: find_file, file_preview, attach_file.

Procedure

The workflow spans two turns. Never collapse them into one.

Turn 1: discovery and preview
  1. Send a short message announcing the search. Example: "going to check the desktop now" / "looking for it now".
  2. Call find_file(query=..., root=..., extensions=[...]). Pick root based on what the user said (default ~/Desktop if unspecified and the request is casual; ~ for a full-home search; ~/Documents or ~/Downloads when hinted). Always pass extensions when the file type is known (e.g. ["pptx","ppt"], ["pdf"]).
  3. Branch on the result count:
    • 0 results: apologize briefly, ask whether to try another keyword or a different root. End the turn. Do not preview.
    • 1 result: continue to step 4. One hit is not implicit confirmation — still preview and still ask.
    • 2–5 results: continue to step 4.
    • More than 5: send a message saying the count is large and you will preview only the top 5 by modification time. Slice to the top 5 and continue.
  4. Send a message announcing the preview step. Example: "found N, rendering thumbnails so you can pick".
  5. Call file_preview(paths=[...]) with all candidate paths in one call.
  6. Produce the final reply for this turn. It must contain:
    • A numbered list of candidates.
    • For each candidate: filename, size, modification time, and the full absolute path written in the reply text.
    • A question asking the user to pick.
  7. Stop this turn. Do not call attach_file yet.

Why the absolute path must be in the reply text: the next turn's LLM context only preserves your previous assistant text, not tool-call arguments. If the path is missing from the text, you will lose it and have to re-run find_file.

Turn 2: confirmation and send
  1. Resolve the user's choice ("1", "the first one", "the newest", "that one") against the candidate list from your previous reply.
  2. If the choice is ambiguous, ask for clarification. Do not guess.
  3. Call attach_file(path=<resolved absolute path>).
  4. Final reply: a short confirmation that the file is on its way.
Show full SKILL.md (271 more words)Show less

Worked Example (English)

User: find the weekly report pptx on my desktop

You, Turn 1:

  • message: "okay, taking a look at the desktop"

  • find_file(query="weekly", root="~/Desktop", extensions=["pptx","ppt"]) → 3 results

  • message: "found 3 — rendering thumbnails so you can pick"

  • file_preview(paths=[...])

  • Final reply:

    Found 3 on your desktop ✨

    [1] weekly_20260410.pptx 2.1MB 2026-04-10 18:23 (newest) /Users/you/Desktop/weekly_20260410.pptx [2] weekly_template.pptx 1.8MB 2026-03-01 10:00 /Users/you/Desktop/weekly_template.pptx [3] weekly_20260403.pptx 2.0MB 2026-04-03 17:50 /Users/you/Desktop/archive/weekly_20260403.pptx

    Thumbnails are above. Which one should I send?

    (Per SOUL.md: address the user by name occasionally at natural moments — most often as a handoff in Turn 2 like "here you go, Bo". Do not wedge it into every sentence.)

User, Turn 2: 1

You, Turn 2:

  • attach_file(path="/Users/you/Desktop/weekly_20260410.pptx")

  • Final reply:

    Here you go — weekly_20260410.pptx ☁️

Worked Example (Chinese)

User: 帮我找桌面上的周报 ppt

You, Turn 1:

  • message: "好呀，我去桌面看看"

  • find_file(query="周报", root="~/Desktop", extensions=["pptx","ppt"]) → 3 results

  • message: "找到 3 个，给你看看缩略图"

  • file_preview(paths=[...])

  • Final reply:

    找到 3 个周报候选 ✨

    [1] 周报_20260410.pptx　2.1MB · 04-10 18:23（最新） /Users/you/Desktop/周报_20260410.pptx [2] 周报_template.pptx　1.8MB · 03-01 /Users/you/Desktop/周报_template.pptx [3] 周报_20260403.pptx　2.0MB · 04-03 /Users/you/Desktop/archive/周报_20260403.pptx

    缩略图都贴上了，要发哪个？

User, Turn 2: 1

You, Turn 2:

  • attach_file(path="/Users/you/Desktop/周报_20260410.pptx")

  • Final reply:

    给你～ 周报_20260410.pptx ☁️

Rules (do not break these)

  • Never call attach_file in the same turn as find_file. The preview-and-ask step is mandatory.
  • Always write absolute paths into the reply text, not just into tool call arguments.
  • One result still requires confirmation. Do not auto-send on a single hit.
  • Progress messages must carry information. "Looking…" with no substance is noise. "Found 3, rendering thumbnails" is good.
  • Stop at zero results. Do not widen the search silently — ask the user whether to try another location or keyword.
  • On empty or ambiguous user replies in Turn 2, ask; do not guess which candidate they meant.

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

Files

Just SKILL.md in syll/skills/file-retrieval of THU-SAGE/syll.

Open the folder on GitHubat commit 3741347

Compare with similar skills

File Retrieval 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.

File Retrieval compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
File Retrieval this skillTHU-SAGE/syll303—~1.3kAutomated safety check: PassMIT
Disk Storage AnalyzerKKKKhazix/khazix-skills21k1 repos~1.4kAutomated safety check: PassMIT
Abp App Nolayersabpframework/abp14k—~575Automated safety check: PassLGPL-3.0
Mole Mac Cleanup CLI Safetytw93/Mole70k—~1.9kAutomated safety check: PassGPL-3.0
Feishu Driveraucvr/Group-Goki1123 repos~587Automated safety check: PassMIT
Azldev Comp Tomlmicrosoft/azurelinux5.3k—~1.8kAutomated safety check: PassMIT

Similar skills

  • Disk Storage Analyzer

    KKKKhazix/khazix-skills

    Scans a Mac or Windows PC read-only to find what fills the disk, grades each item by how safe it is to clean and builds an interactive HTML report.

    21k GitHub starsUsed in 1 repo~1.4k tokens
    Productivity & AutomationAuto-check passed

  • Abp App Nolayers

    abpframework/abp

    ABP Single-Layer (No-Layers / nolayers) application template - single project structure, feature-based file organization, no separate Domain/Application.Contracts projects.

    14k GitHub stars~575 tokensUpdated today
    Productivity & AutomationAuto-check passed

  • Mole Mac Cleanup CLI Safety

    tw93/Mole

    Teaches an agent to drive the Mole (mo) Mac cleaning CLI safely: preview first, use JSON output, and leave destructive runs to the user.

    70k GitHub stars~1.9k tokensUpdated today
    Productivity & AutomationAuto-check passed

  • Feishu Drive

    raucvr/Group-Goki

    Feishu cloud storage file management. An agent skill from raucvr/Group-Goki.

    112 GitHub starsUsed in 3 repos~587 tokens
    Productivity & AutomationAuto-check passed

  • Azldev Comp Toml

    microsoft/azurelinux

    Official

    Read this before authoring, editing, or reviewing a .comp.toml file; do not work from memory.

    5.3k GitHub stars~1.8k tokensUpdated today
    Productivity & AutomationAuto-check passed

  • Baidu Netdisk File Manager

    baidu-netdisk/bdpan-storage

    Manages files on Baidu Netdisk - upload, download, transfer, share, search, move, copy, rename and create folders - plus backing up or restoring agent memory.

    273 GitHub stars~4.5k tokensUpdated 1 mo ago
    Productivity & AutomationAuto-check: notes

More from THU-SAGE/syll

All 8 skills in this repo

  • Audition Voice Cleanup

    THU-SAGE/syll

    Cleans a voice recording by driving Adobe Audition on a macOS host to reduce hiss, hum, background noise and sibilance, after asking for your consent.

    303 GitHub stars~1.2k tokensUpdated 4 mo ago
    Auto-check passed

  • Photoshop Background Cutout

    THU-SAGE/syll

    Removes an image background and exports a transparent PNG by driving the real Adobe Photoshop app on a macOS host, after asking your permission to take over the screen.

    303 GitHub stars~1.2k tokensUpdated 4 mo ago
    Auto-check passed

  • Desktop GUI Agent

    THU-SAGE/syll

    Controls desktop applications through screenshots: a vision model reads the screen and returns click, type and scroll actions that pyautogui then performs.

    303 GitHub stars~662 tokensUpdated 4 mo ago
    Auto-check passed

  • Morning News Podcast

    THU-SAGE/syll

    Builds a short spoken morning news briefing from a few web searches and turns it into one audio clip, on request or on a schedule.

    303 GitHub stars~533 tokensUpdated 4 mo ago
    Auto-check passed

  • HoYoLAB Check-in Simulator

    THU-SAGE/syll

    Produces a clearly labeled, research-based stand-in for a Genshin Impact or Honkai: Star Rail daily check-in when no real sign-in can be run.

    303 GitHub stars~551 tokensUpdated 4 mo ago
    Auto-check passed

  • Local Mail Sim

    THU-SAGE/syll

    Simulate an overnight local mail summary when there is no real local mailbox integration or recorded GUI workflow available.

    303 GitHub stars~355 tokensUpdated 4 mo ago
    Auto-check passed

Categories

Questions about File Retrieval

What does File Retrieval do?

Finds a file on the local machine, shows previews of the candidates, and sends the one you pick back through the current chat channel after confirmation. The skill uses three tools, `find_file`, `file_preview` and `attach_file`, across two separate turns. In the first turn the agent announces the search and calls `find_file` with a query, a search root such as the desktop, documents, downloads or home folder, and file extensions when the type is known, then branches on the number of hits.

When should I use File Retrieval?

File Retrieval fits situations like: asked to find a file on the user's computer and send it; locating a presentation or PDF on the desktop or in Downloads; choosing between several similarly named files by preview.

How do I install File Retrieval in Claude Code?

Run `npx skills add THU-SAGE/syll --skill file-retrieval -a claude-code`. Or copy the skill folder (syll/skills/file-retrieval in THU-SAGE/syll) into .claude/skills/file-retrieval in your project. Claude Code loads it when a task matches its description.

How do I install File Retrieval in Codex?

Run `npx skills add THU-SAGE/syll --skill file-retrieval -a codex`. Or copy the skill folder (syll/skills/file-retrieval in THU-SAGE/syll) into .agents/skills/file-retrieval in your project. Codex loads it when a task matches its description.

Can I use File Retrieval 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 THU-SAGE/syll --skill file-retrieval -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/file-retrieval, .gemini/skills/file-retrieval, .github/skills/file-retrieval and .opencode/skills/file-retrieval in your project.

What does File Retrieval need to run?

SKILL.md names no scripts, command-line tools or credentials: File Retrieval is instructions for the agent only. Our summary lists: Agent tools named `find_file`, `file_preview` and `attach_file`; A chat channel that can deliver file attachments.

Does File Retrieval 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 File Retrieval 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. Review the folder before installing.

What licence does File Retrieval use?

File Retrieval is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does File Retrieval use?

About 1.3k tokens (SKILL.md is roughly 5.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to File Retrieval?

Skills that share tags, products or a category with File Retrieval: Disk Storage Analyzer (KKKKhazix/khazix-skills, 21k stars), Abp App Nolayers (abpframework/abp, 14k stars), Mole Mac Cleanup CLI Safety (tw93/Mole, 70k stars) and Feishu Drive (raucvr/Group-Goki, 112 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains File Retrieval?

THU-SAGE (a GitHub organization) maintains it in THU-SAGE/syll, which has 303 GitHub stars. The repository holds 8 skills in this directory. The repository was last updated on June 9, 2026.

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