MCP Tools vs Agent Skills: Understanding the Two-Layer Architecture in Flutter Skills

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, 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 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 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 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 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:

# 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.

Using MCP Tools Directly

For scenarios requiring fine-grained control, you can invoke MCP tools directly without the skill wrapper:

# 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}