# MCP Tools vs Agent Skills: Understanding the Two-Layer Architecture in Flutter Skills > Understand the Flutter skills two-layer architecture differentiate MCP tools from Agent Skills. Learn how high-level workflows orchestrate command-line capabilities for development tasks. - Repository: [Flutter/skills](https://github.com/flutter/skills) - Tags: deep-dive - Published: 2026-05-09 --- **MCP tools provide raw command-line capabilities, while Agent Skills are high-level workflows that teach agents how to orchestrate those tools to accomplish specific development tasks.** The `flutter/skills` repository implements a dual-layer system where **MCP (Machine-Code-Protocol) tools** and **Agent Skills** work together to enable AI-assisted Flutter development. Understanding the distinction between these two concepts is essential for effectively extending agent capabilities and creating reusable automation workflows. ## What Are MCP Tools? **MCP tools** are low-level utilities that expose concrete operations an agent can invoke directly. These utilities provide access to specialized functionality but contain no logic about *when* or *how* to combine them into meaningful tasks. ### Technical Implementation In the `flutter/skills` codebase, MCP tools are implemented as command-line programs and hooks that live under the `tool/` directory. Each tool performs a discrete operation such as code formatting, static analysis, or file generation. According to the [README.md](https://github.com/flutter/skills/blob/main/README.md), MCP gives an agent "access to specialized tools" but does not instruct the agent on workflow orchestration. ### Example MCP Tools in flutter/skills The repository includes several concrete MCP tool implementations: - **`dart format`** functionality is exposed through `tool/dart_hooks/lib/src/dart_format_hook.dart`, which handles Dart code formatting operations - **`dart analyze`** capabilities reside in `tool/dart_hooks/lib/src/dart_analyze_hook.dart`, providing static analysis features - Additional utilities like `dart_skills_lint` offer specialized linting operations These files expose raw capabilities that any agent or skill can invoke, but they operate independently without knowledge of broader development workflows. ## What Are Agent Skills? **Agent Skills** are higher-level, self-contained bundles that encode best-practice workflows for specific Flutter development tasks. A skill teaches the agent *how* to sequence MCP tool invocations to achieve a user goal, handling configuration, file generation, and implementation details. ### Skill Structure and Configuration Each skill resides in its own folder under the `skills/` directory and contains a [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) file that serves as the instruction manual for the agent. As noted in the repository documentation, "Skills are essentially simple folders of files that can be seen as complementary to MCP." The [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) file maps user intent to specific sequences of MCP tool calls. For example, the `flutter-add-widget-test` skill at [`skills/flutter-add-widget-test/SKILL.md`](https://github.com/flutter/skills/blob/main/skills/flutter-add-widget-test/SKILL.md) defines steps to generate widget tests while automatically invoking formatting and analysis tools. ### How Skills Orchestrate MCP Tools When an agent executes a skill, it follows the workflow defined in [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) to chain together multiple MCP tool invocations. A typical skill workflow might: 1. Generate boilerplate code or configuration files 2. Invoke `dart format` (MCP tool) to ensure code style consistency 3. Execute `dart analyze` (MCP tool) to verify compilation and catch static errors 4. Return results to the user with appropriate context This orchestration logic is handled by the command infrastructure in `tool/generator/lib/src/commands/base_skill_command.dart`, which provides the core execution framework for the `skills` CLI. ## Key Differences Between MCP Tools and Agent Skills The relationship between these two layers can be summarized as **capabilities versus workflows**: - **MCP tools** provide **raw capabilities**—individual commands like `dart format` or `dart analyze` that perform specific technical operations - **Agent Skills** provide **workflow orchestration**—high-level instructions that combine MCP tools into user-friendly task completion sequences A practical example illustrates this distinction: while the `dart format` MCP tool can format a single file, the `flutter-add-widget-test` Agent Skill orchestrates file creation, multiple formatting passes, and analysis to deliver a complete widget testing solution. ## Practical Usage Examples ### Running an Agent Skill Skills are executed through the `skills` CLI, which handles installation and orchestration: ```bash # Install all Flutter skills npx skills add flutter/skills --skill '*' --agent universal # Execute a specific skill to add a widget test npx skills run flutter-add-widget-test --prompt "Add a widget test for the CustomButton" ``` Behind the scenes, the `base_skill_command.dart` class processes the skill definition and coordinates MCP tool invocations based on the logic defined in the skill's [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md). ### Using MCP Tools Directly For scenarios requiring fine-grained control, you can invoke MCP tools directly without the skill wrapper: ```bash # Format a specific file dart format lib/widgets/custom_button.dart # Run static analysis dart analyze lib/widgets/custom_button.dart ``` Direct tool invocation bypasses the workflow logic but requires manual orchestration if multiple operations are needed. ## Summary - **MCP tools** are low-level utilities in `tool/` that expose concrete operations like formatting and analysis - **Agent Skills** are high-level workflow bundles in `skills/` that teach agents *how* to combine MCP tools for specific tasks - The [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) file format defines skill behavior and orchestration logic - Skills use the command infrastructure in `tool/generator/lib/src/commands/base_skill_command.dart` to execute workflows - Direct MCP tool usage offers granular control, while skills provide automated best-practice workflows ## Frequently Asked Questions ### Can MCP tools be used without Agent Skills? Yes, MCP tools can be invoked directly from the command line or by agents without skill wrappers. For example, you can run `dart format` directly on any Dart file. However, using tools directly requires manual orchestration and lacks the best-practice guidance encoded in skill definitions. ### How do I create a custom Agent Skill for my Flutter project? Create a new folder under `skills/` containing a [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) file that describes the task, required inputs, and the sequence of MCP tool invocations needed. The skill should reference specific MCP tools like those in `tool/dart_hooks/lib/src/` to perform underlying operations while the [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) file handles the high-level workflow logic. ### What is the relationship between the `skills` CLI and MCP tools? The `skills` CLI (implemented in `tool/generator/lib/src/commands/`) acts as the execution layer that reads skill definitions and invokes the appropriate MCP tools. When you run `npx skills run`, the CLI parses the skill's instructions and translates them into concrete calls to MCP tool implementations, handling the orchestration automatically.