How MCP and SKILL.md Work Together: Practical Examples

The best AI agent setups don't choose between MCP and SKILL.md. They use both. MCP gives agents access to external tools and data. Skills give agents the expertise to use those tools effectively. Together, they create workflows that are more capable than either approach alone.

The pattern

Every combined workflow follows the same structure:

1. The SKILL.md file teaches the agent what to do, in what order, and how to handle edge cases
2. The MCP server gives the agent access to the tools and data it needs to execute

Without the skill, the agent has tools but no methodology. Without the MCP server, the agent has methodology but no access. Both are needed.

Example 1: Database migration review

The skill: migration-auditor teaches the agent how to review database migrations. It provides a checklist: check for table locking hazards, identify potential data loss, verify rollback steps exist, flag missing indexes, and check for unsafe operations on large tables. The skill knows the difference between a PostgreSQL ALTER TABLE that locks the table and one that doesn't.

The MCP server: a PostgreSQL MCP server that connects to your staging database. It can query table sizes, check existing indexes, inspect current schema, and estimate how long an ALTER TABLE will take based on row count.

Together: when you ask "review this migration," the agent loads the migration-auditor skill for methodology, then uses the PostgreSQL MCP server to check the actual state of the database. Instead of guessing whether a table has 1,000 rows or 10 million (which determines if a migration is safe), it checks. Instead of guessing what indexes already exist, it queries the schema. The skill tells it what to look for. The MCP server lets it look.

Example 2: Deployment with safety checks

The skill: a deployment skill that codifies your team's release process. It knows to check that tests pass, staging is green, no critical alerts are firing, the changelog is updated, and the PR has been approved before deploying. It knows to deploy to staging first, wait 10 minutes, check error rates, then proceed to production.

The MCP server: servers for your CI/CD platform (GitHub Actions or similar), your monitoring tool (Datadog, Grafana), and your cloud provider (AWS, Vercel, Netlify).

Together: the agent follows the deployment skill's checklist but actually executes each step. It checks CI via the GitHub MCP server, queries error rates via the monitoring MCP server, and triggers the deployment via the cloud provider MCP server. The skill is the playbook. The MCP servers are the hands.

Example 3: Code review with context

The skill: code-reviewer teaches the agent a structured review methodology. Check security vulnerabilities first (SQL injection, XSS, auth bypasses). Then logic errors. Then performance. Then style. Organize findings by severity. Include file paths, line numbers, and fix suggestions.

The MCP server: a GitHub MCP server that can read PR details, view file diffs, check CI status, read existing review comments, and post review comments.

Together: the agent loads the code review skill for its methodology, then uses the GitHub MCP server to read the actual PR. It can see the diff in context, check if tests passed, read what other reviewers said, and post its own review comments directly on the PR. Without MCP, the agent could review code you paste into the chat. With MCP, it reviews the PR in place.

Example 4: Documentation from live data

The skill: readme-generator teaches the agent how to structure project documentation. It knows to include installation steps, usage examples, configuration options, contributing guidelines, and a tech stack overview. It knows to scan package.json for dependencies and to check for existing docs to avoid overwriting.

The MCP server: a file system MCP server with access to your project, plus optionally a server for your documentation platform (Notion, Confluence, Mintlify).

Together: the agent follows the documentation skill's structure but pulls real data. It reads the actual package.json, scans the actual directory structure, finds actual configuration files, and checks the actual test suite. If connected to Notion via MCP, it can also publish the finished documentation directly.

Setting up combined workflows

To use skills and MCP servers together, install both:

1. Download skills to your agent's skills directory (e.g., ~/.claude/skills/)
2. Add MCP servers to your agent's config file (e.g., ~/.claude.json)

The agent discovers both automatically. When you make a request, it loads relevant skills for methodology and calls relevant MCP tools for access. You don't need to manually coordinate them.

For example, with a migration-auditor skill installed and a PostgreSQL MCP server configured, just ask: "Review the migration files in this PR for safety issues." The agent handles the rest.

Building your own combined workflows

Think about your team's processes and identify two things:

1. What methodology or checklist do you follow? That becomes a skill.
2. What tools or data do you need to execute that process? That becomes an MCP server.

Write the skill first (it's just a markdown file). Then find or build the MCP server. Test them separately, then together.

For curated, security-scanned skills to pair with your MCP servers, browse the Agensi marketplace. For more on building MCP servers, see our tutorial on building your first MCP server. To understand the fundamentals, read what is the Model Context Protocol.

---

Related articles

• What Is the Model Context Protocol (MCP)? A Developer's Guide
• MCP vs SKILL.md: What's the Difference and When to Use Each
• How to Build Your First MCP Server in 2026
• The Complete Guide to AI Agent Configuration in 2026