Important Notice:
The Eagle MCP plugin requires Eagle 4.0 Build 12 (2025-09-14) or later to function properly, and is currently in Beta -- stability is not yet fully mature. Additionally, different AI models vary in capability and performance, and AI may still produce incorrect or unexpected results. We strongly recommend that users create a complete backup of all data beforehand, and carefully review the task details and execution plan before each Agent run to avoid unintended data modifications caused by Agent misjudgment or model limitations.

In addition to the MCP mode, Eagle also offers Eagle Skill as a lightweight alternative that lets your AI assistant directly manage your Eagle library -- turning tasks like "tag cleanup, categorization, translation, and batch management" from tedious manual work into simple natural language commands.

If you're already using Eagle MCP, you might be wondering: how is Skill different from MCP? Here are the three key advantages of Skill mode:

Significant Token Savings: MCP mode loads all tool definitions into the context window, while Skill mode only loads a brief Skill description, dramatically reducing Token consumption.
On-Demand Loading: Detailed tool reference documents are only loaded when the AI actually needs them, further reducing the cost of each conversation.
Zero Configuration: No need to set up an MCP client or edit JSON config files -- just copy the Skill package into your AI tool's Skills folder and you're ready to go.

AI tools that currently support Skills include: Claude Code, OpenClaw (Lobster), Gemini CLI, Codex, Google Anti-Gravity, and more. This guide uses Claude Code as an example to walk you through the complete Eagle Skill setup process, including: installing and launching the Eagle MCP plugin, installing the Skill package, and verifying it in your AI tool -- so you can go from zero to having AI integrated into your asset management workflow.

What is a Skill?

Think of a Skill as a "skill pack" for AI: a set of pre-written instructions and tool references that teach an AI how to use a specific tool or perform a specific task. Once you install Eagle Skill, your AI tool can understand how to interact with your Eagle library -- searching assets, managing tags, organizing folders -- all through natural language.

Unlike MCP, a Skill doesn't require additional server protocol configuration. It's a folder containing a SKILL.md description file and helper scripts -- place it in the designated location and the AI will automatically detect and load it. Skills follow the Agent Skills open standard, which is currently supported by multiple mainstream AI tools including Claude Code, OpenClaw (Lobster), Gemini CLI, Codex, Google Anti-Gravity, and more.

Below is an introductory video about Skills made by the Anthropic team. We recommend watching it for a quick overview of how Skills work:

What Can Eagle Skill Do?

Eagle Skill packages a set of capabilities tailored to asset management workflows, closely aligned with design and creative needs.

Core Features

Intelligent Tag System Analysis

Analyzes your tag usage patterns, identifies synonym groups (e.g., "cat / kitty / feline"), spelling variants, and usage frequency, then provides recommendations for merging, retiring, or standardizing tags.
Natural Language Control of Complex Tasks

You can issue "conditional query and organization" instructions -- for example, limiting the scope by folder, star rating, time range, or existing tag sets.
Cloud and Local Model Integration

Choose between cloud or local models based on your budget and privacy requirements (actual support depends on your AI tool and model service).

Model Recommendation: Claude Sonnet 4.5 and Later
If you're using Eagle Skill for complex or multi-step reasoning tasks (such as tag group analysis or batch classification suggestions), we strongly recommend using Claude Sonnet 4.5 or later versions. The Claude series is specifically trained for "Tool Use" and can more accurately understand instruction structures and return formats, performing particularly well in scenarios that require multiple tool calls and structured results. If budget is a concern, Claude Haiku 4.5 is also a viable option -- its tool-calling accuracy is slightly lower than Sonnet's, but it offers advantages in speed and cost, making it suitable for testing phases or non-critical tasks.

Installing Eagle Skill

Step 1: Install the Eagle MCP Plugin

Eagle Skill relies on the local server provided by the Eagle MCP plugin, so the first step is to install and enable that plugin.

Open the Eagle application
Click "Plugins" in the top menu bar, then select "Plugin Center"
Type "MCP" in the search bar
Find "Eagle MCP" and click "Install"
After installation, click the "Enable" button in the plugin list
On first activation, the MCP server will start automatically (default port: 41596), and the system will display the server status: Running

Step 2: Install the Skill via the Plugin Panel

In the Eagle MCP plugin panel, find the "Eagle Skill Introduction" section
Click the "Install Skill" button in the upper-right corner (with a + icon)
A folder picker dialog will appear. Navigate to the Skills folder for your AI tool. For Claude Code:
- macOS / Linux: ~/.claude/skills/
- Windows: C:\Users\YourUsername\.claude\skills\
If you're using another Skill-compatible tool (such as OpenClaw, Gemini CLI, Codex, Google Anti-Gravity, etc.), select the corresponding Skills folder for that tool.
Once you select the folder, the plugin will automatically copy the eagle-skill package to the target location and open the file manager so you can confirm the installation

After installation, your Skills folder structure should look like this:

~/.claude/skills/
└── eagle-skill/
    ├── SKILL.md              # Main Skill description file
    ├── scripts/
    │   └── eagle-api-cli.js  # CLI tool script
    └── references/           # Tool reference documents
        ├── app-tools.md
        ├── item-tools.md
        ├── folder-tools.md
        ├── tag-tools.md
        ├── tag-group-tools.md
        └── ai-search-tools.md

Manual Installation
If you prefer to install manually, you can directly copy the skills/eagle-skill folder from the Eagle MCP plugin directory into ~/.claude/skills/.

Step 3: Verify in Your AI Tool

Using Claude Code as an example:

Open your terminal and type claude to launch Claude Code
Ask Claude: "What Skills do you have available?" and confirm that eagle skill appears in the response
Run a test: Ask "What version of Eagle am I running?"
If the AI can successfully call the Eagle API and return the version information, Eagle Skill is installed and working correctly

If you're using a different AI tool, the verification process is similar: open the tool and try asking an Eagle-related question.

Privacy and Data Disclosure (Must Read)

When using Eagle Skill, whether data "leaves your computer" depends primarily on whether you're using a cloud model or a local model:

If You're Using a Cloud Model (Cloud LLM)

During inference, information such as "file names, tags, annotations, search queries, and summaries" may be sent to the model provider to complete reasoning and generate responses.

Recommended Practices:

Avoid having the Agent batch-process highly sensitive assets (contracts, personal information, unreleased projects)
Test with a small folder first, and expand scope only after confirming the risk is acceptable

If You're Using a Local Model (Local LLM)

Data typically does not need to be sent to the cloud, so the privacy risk is relatively lower; however, local models vary more significantly in quality, speed, and tool-calling stability.

Note: The Eagle MCP server itself runs locally and is responsible for translating the AI's "instructions" into "controlled operations" within Eagle. Any actual data transmission typically occurs during the inference phase of your chosen model, not within MCP itself.

Permissions and Safety Best Practices (Reducing Misoperation Risk)

Eagle Skill is very powerful, which also means it can "change a lot of content at once." We recommend consistently following this SOP:

Analyze First, Execute Later: Have the AI output its recommendations and an "expected change list" first; only proceed after you've confirmed everything looks correct
Start Small: Begin with a small number of files or a single folder, then gradually expand
Break Tasks Down: Avoid organizing your entire library in a single command -- splitting into 2-5 steps gives you more control
Define Clear Scope: Specify folders, file counts, time ranges, or tag sets
Start with Read-Only Tasks: Use version queries, statistics, or candidate lists to validate the workflow before performing batch modifications

Eagle Skill Practical Examples (Ready to Copy and Use)

We recommend prefacing each example with "Please output the change list first, don't execute directly" to help build safe usage habits.

Example 1: Multi-Language Tag Translation (Output List First)

Scan the tags in the folder "/Japanese Assets",
find all tags containing Japanese characters and translate them to English.
First, output a "Japanese tag -> English tag" mapping list
along with the number of affected files.
Wait for my confirmation before batch-adding the English tags.

Example 2: Tag Usage Frequency Analysis and Cleanup Suggestions (Read-Only)

Please analyze my Eagle tag usage:
1) List all tags used fewer than 3 times
2) Identify potentially synonymous or duplicate tag groups (including typos)
3) Provide recommendations: which should be merged, which should be retired
Output the report only -- do not make any changes.

Example 3: Classification Suggestions for Newly Imported Files (Suggest First, Move Later)

Analyze my 10 most recently added files.
Based on file types and the existing folder structure,
first output a "suggested classification path + suggested tags" list,
and note the confidence score or reasoning for each suggestion.
Wait for my confirmation before executing the moves and applying tags.

Example 4: Single File Content Analysis and Full Archival Suggestion (Analyze First)

Please output the change list first, do not execute directly.

Analyze the file I currently have selected, and complete the following in order:
1) Read the file's full path and filename
2) Analyze the image content and generate a search-friendly description (objective and specific)
3) Suggest a set of tags (avoid overly abstract terms, prefer reusable keywords)
4) Based on my existing folder structure, suggest the most appropriate classification path (single path)

Please output as a list:
- Filename
- Suggested description
- Suggested tags (list)
- Suggested folder path
- Reasoning or confidence note for each suggestion

Wait for my confirmation before writing the description, applying tags, and moving the file.

Example 5: Domain-Specific Folder Structure for a Blank Library (Output Structure Only)

Please output the structure suggestion only, do not create any folders.

This is a brand-new, empty Eagle library.
I plan to use it specifically for organizing "Game Design" inspiration images.

Please design a folder classification structure with the following requirements:
1) Approximately 5 "top-level categories"
2) Each top-level category should contain 5-10 "subcategories"
3) For each top-level category, provide:
   - Description of folder purpose
   - Suggested icon type
   - Icon color (for visual distinction -- avoid duplicating colors across categories)

Output format should include:
- Top-level category name
  - Purpose description
  - Icon suggestion (shape / type)
  - Icon color
  - Subcategory list (with brief descriptions)

The overall design should prioritize "practical, long-term scalable, and timeless."
Wait for my confirmation of the overall structure before actually creating the folders.

FAQ (Troubleshooting)

Q1: The AI tool can't find the Skill after installation?

Confirm that the eagle-skill folder is correctly placed in your AI tool's Skills folder (e.g., ~/.claude/skills/eagle-skill/ for Claude Code)
Confirm the folder contains a SKILL.md file
Try restarting the AI tool (fully close and reopen it)
Ask the AI "What Skills do you have available?" to check if it has been loaded

Q2: The Skill is present but the AI doesn't call Eagle tools?

Confirm that Eagle is running and the Eagle MCP plugin shows Running (the Skill still requires the local server to be active)
Test with read-only queries first (version check, tag statistics, candidate lists)
In some cases, explicitly adding: "Please use Eagle Skill to query this" can help
Verify the local server endpoint is accessible: http://localhost:41596/mcp

Q3: Results look abnormal or incorrect

Ask for a "change list" and "impact scope" first, before applying anything
Break the task down, narrow the folder scope, and reduce the number of files processed per batch

Q4: What's the difference between Skill and MCP? Which should I use?

Comparison	MCP Mode	Skill Mode
Supported Tools	Claude Desktop, Cursor, Claude Code, and all MCP clients	Claude Code, OpenClaw (Lobster), Gemini CLI, Codex, Google Anti-Gravity, and other tools supporting the Agent Skills standard
Token Consumption	Higher (all tool definitions loaded into the context window)	Lower (only the Skill description is loaded; reference documents are loaded on demand)
Configuration	Requires editing JSON config files or configuring through the tool's UI	Just copy the folder to `~/.claude/skills/`
Server Requirement	Required (local server provided by the Eagle MCP plugin)	Required (also depends on the Eagle MCP plugin's local server)
Best For	Users of Cursor, Claude Desktop, and other various AI tools	Users of Skill-compatible AI tools who want to save Tokens and simplify setup

In short: If your AI tool supports Skills (such as Claude Code, OpenClaw, Gemini CLI, Codex, or Google Anti-Gravity), we recommend using Skill mode for better Token efficiency and simpler setup. If you're using Cursor, Claude Desktop, or other tools that only support MCP, please refer to the Eagle MCP Server Configuration Guide for setup instructions. Both modes can be installed simultaneously without conflict.

Guide to the Eagle Skill