Guide · Agent skill
How to use the gifgrep agent skill: search, download and extract GIFs
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gifgrep skill lets an AI agent search GIF providers such as Tenor and Giphy, preview the results, download GIFs, and pull a single still frame or a PNG grid of sampled frames from an animation. It is for people who want an agent to handle GIF lookups and quick visual reviews without typing the commands themselves. By the end of this guide you will know what the skill needs, how to install it, how to phrase requests so the agent triggers it, and which safety points to check.
GIF Search and Extractspinabot/brigade · MIT Download the skill Quick start
- 1Install gifgrep. Install the gifgrep command with Homebrew (steipete/tap/gifgrep) or Go (github.com/steipete/gifgrep/cmd/gifgrep@latest).
- 2Download and unzip the skill. Get the gifgrep ZIP from our page and unzip it so SKILL.md sits in a gifgrep folder.
- 3Place the skill folder. Move the folder to ~/.claude/skills/ for personal use or to .claude/skills/ in a project, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 4Set API keys if needed. Set GIPHY_API_KEY if you plan to use Giphy. TENOR_API_KEY is optional because a demo key is used when it is unset.
- 5Ask for what you need. Describe the GIF search or extraction in plain language, for example asking for five cat GIFs or a contact sheet from a file.
- 6Review the result. Check the GIFs or PNG output the agent produced, and confirm the licence before using any GIF commercially.
What is an agent skill, and what does gifgrep let the agent do?
An agent skill is a folder containing a SKILL.md file that teaches an AI agent how to use a particular tool. The gifgrep skill teaches the agent to use the gifgrep command-line tool.
With the skill installed, the agent can search GIF providers (Tenor and Giphy), download results to your Downloads folder, and extract a single still frame or a sheet from a GIF. A sheet is a single PNG grid of sampled frames, useful for quick review in docs, pull requests or chat.
- Search GIF providers by keyword, with --source set to auto, tenor or giphy
- Download matching GIFs to ~/Downloads
- Extract one still frame at a given time as a PNG
- Build a PNG sheet of sampled frames, with control over frame count, columns and spacing
Install gifgrep before installing the skill
The skill depends on the gifgrep command-line tool, which must be installed first. The skill's metadata lists two install routes: Homebrew and Go.
Use the Homebrew formula steipete/tap/gifgrep, or install the Go module github.com/steipete/gifgrep/cmd/gifgrep@latest. Either way, the gifgrep binary must be available on your system.
- Homebrew formula: steipete/tap/gifgrep
- Go module: github.com/steipete/gifgrep/cmd/gifgrep@latest
gifgrep cats --max 5Install the skill from the ZIP
Download the gifgrep ZIP from our page and unzip it. The skill is a single file, SKILL.md. Place the unzipped gifgrep folder in one of these locations:
For a personal skill available across projects, use ~/.claude/skills/. For a skill limited to one project, use the .claude/skills/ folder inside that project.
In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/gifgrep/
- Project only: .claude/skills/gifgrep/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Set up API keys for the providers you use
Tenor works without configuration because a Tenor demo key is used if TENOR_API_KEY is not set. Setting your own TENOR_API_KEY is optional.
Giphy requires your own GIPHY_API_KEY environment variable whenever you use --source giphy. Without it, the Giphy provider will not work.
- GIPHY_API_KEY: required only for --source giphy
- TENOR_API_KEY: optional; a Tenor demo key is used if unset
How to trigger the skill with natural requests
You do not need to name the command. Describe the job in plain language and mention GIFs, a reaction, or a still or sheet from a GIF. The agent chooses gifgrep when the request matches the skill's description.
Good requests name the goal and the output you want, such as a single download or a short list to pick from.
- "Find a reaction GIF of an office handshake and download the best one."
- "Show me five GIFs of cats so I can pick one for the post."
- "Make a 3 by 3 contact sheet of nine frames from clip.gif for my PR description."
- "Pull the frame at 1.5 seconds from clip.gif as a PNG."
Commands the skill uses
These are the main commands from the skill source. The agent runs them for you, but reading them helps you check what it did.
Search with --max to limit results, --format url for pipe-friendly output, or --json for structured results. Use tui to browse interactively. Add --download to save results to ~/Downloads, and --reveal to show the last download in Finder.
- Search: gifgrep cats --max 5
- URLs only: gifgrep cats --format url | head -n 5
- JSON: gifgrep search --json cats | jq '.[0].url'
- Interactive browser: gifgrep tui "office handshake"
- Download one: gifgrep cats --download --max 1 --format url
gifgrep still ./clip.gif --at 1.5s -o still.png
gifgrep sheet ./clip.gif --frames 9 --cols 3 -o sheet.pngSafety notes: scripts and network use
The skill does not run scripts, according to its listing. It does use the network, because gifgrep sends searches to GIF providers and downloads files from them. API keys are read from environment variables.
The skill source does not address copyright or licensing of search results. Check the terms of any GIF before using it commercially.
- Network: yes, searches go to Tenor or Giphy and downloads come from them
- Scripts: none listed for this skill
- Keys: read from GIPHY_API_KEY and TENOR_API_KEY environment variables
- Licensing: check each GIF's terms before commercial use
Tips for better results
Use --format url when the agent or a script needs only links. Use --json when you need fields such as title, tags, width and height. Tune sheets with --frames for the count, --cols for grid width and --padding for spacing.
If previews look wrong, the source lists two environment tweaks: GIFGREP_SOFTWARE_ANIM=1 forces software animation, and GIFGREP_CELL_ASPECT=0.5 adjusts preview geometry. Thumbnail previews with --thumbs work only in Kitty and Ghostty terminals.
- Use --source tenor or --source giphy to pick a provider, or leave the default auto
- --thumbs shows still previews only in Kitty and Ghostty
- Set GIFGREP_SOFTWARE_ANIM=1 to force software animation
What people use it for
- Finding a reaction GIF to add to a chat message or social post
- Previewing a GIF's frames as one PNG sheet for a pull request or documentation
- Extracting a still frame at a set time to use as a thumbnail or image
- Scanning many GIF search results quickly from the terminal
Frequently asked questions
Is the gifgrep skill free?
The skill source does not state a price or licence terms for the skill beyond its listing, so this page makes no claim about cost. Tenor works with a built-in demo key if you set no key of your own. Giphy requires your own GIPHY_API_KEY, and the licence of each downloaded GIF is a separate question the skill does not address.
What do I need to install before using gifgrep?
You need the gifgrep command-line tool, installed with Homebrew from steipete/tap/gifgrep or with Go from github.com/steipete/gifgrep/cmd/gifgrep@latest. You also need an agent environment that supports skills, such as Claude Code or the Claude apps. Giphy searches need a GIPHY_API_KEY.
Why does Giphy search not work for me?
The skill's source says the GIPHY_API_KEY environment variable is required for --source giphy. Without your own key, that provider will not work. Tenor still works without a key because a demo key is used if TENOR_API_KEY is unset.
Where are downloaded GIFs saved?
The --download option saves files to ~/Downloads. Adding --reveal shows the last download in Finder.
Can I use the GIFs commercially?
The skill does not address copyright or licensing of search results. Check the terms of each GIF and its provider before using it in commercial work.
Does gifgrep run scripts or send my data anywhere?
The skill lists no scripts and does run network requests, because searches go to GIF providers such as Tenor and Giphy and downloads come from them. Your API keys are read from environment variables.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits creators, marketers and developers who want an agent to find reaction GIFs or make quick visual previews from the terminal, and who are comfortable installing a command-line tool. It is a poor fit if you cannot install gifgrep, need Giphy without your own API key, or must confirm licences for commercial use, since the skill does not handle those.
Download the skill