PromptForward

•11 min read•By PromptForward Team

Claude Code: Skills Beats MCP (One Tiny File at a Time)

Claude Code’s file-based Skills bundle docs and scripts so your AI can explain and execute work—often simpler, cheaper, and better than MCP for everyday local/dev workflows.

Claude Code: Skills Beats MCP (One Tiny File at a Time)

If you’ve played with AI "agents" before, you probably know the pattern: you add a tool, then another, then a server and some configs, and suddenly you’ve built a mini platform just to run a few scripts. Claude Code’s Skills are the opposite of that. They’re tiny, boring files — and that’s exactly why they’re awesome.

In this post, I’ll show you why Skills fit everyday work so well, why they often beat MCP for local/dev workflows, and how to get started in minutes.

What is a Skill, really?

A Skill is just a folder. The important file is usually SKILL.md, a small markdown document that tells Claude what the skill is called, when to use it, and how to use it. You can add whatever else helps — a reference.md, a few example snippets, scripts in bash or Python, even templates or configs. The model learns the job from this small bundle and then decides on its own when to use it, within the permissions you grant in your configuration.

The frontmatter in SKILL.md should include a concise name and description. The description is critical — Claude uses it to decide when to invoke a Skill — and should be kept short and specific. You can also include optional fields like version (to track iterations) and dependencies (to list required packages). This metadata acts as the first layer of progressive disclosure: just enough for discovery without pulling in all the details.

So instead of typing a special command like “/deploy_staging_tool please,” you just write, “Deploy the current branch to staging and run a quick smoke test.” If you have a deploy-staging Skill, and you’ve allowed it in your setup, Claude reads the description, selects the right Skill, and follows the steps or scripts. No extra syntax, no ceremony.

1. A Skill can both explain and do

In most setups, the documentation, the scripts, and the agent logic live in different places. Skills let you bundle all of that in one place. The same Skill that teaches a teammate how your release process works can also run the exact commands to execute it.

Example SKILL.md:

---
name: deploy-staging
description: Deploy the current branch to staging and run smoke tests. Use when the user asks to deploy to staging.
---

# Deploy to Staging

1. Run `scripts/deploy-staging.sh` with the current branch name.
2. Wait for it to finish.
3. Run `scripts/smoke-tests.sh`.
4. Summarize any failures for the user and suggest next steps.

You might include scripts/deploy-staging.sh, scripts/smoke-tests.sh, and a reference.md for deeper detail. Claude can then explain the process to a new teammate and actually run it when you ask. Same Skill, two uses — learning and doing — without a separate runbook, Confluence page, or agent config.

2. Bash Skills = huge power, tiny context

Here’s a big reason Skills shine for local work: a Skill can lean on bash, and bash can lean on the rest of your tools. You don’t need to pour entire datasets into context or paste giant logs and CSVs into chat. Let grep, awk, and jq do the heavy lifting, then send only the relevant snippets back to the model.

For example, a Skill for log analysis:

---
name: log-investigator
description: Help diagnose issues by scanning large log files with bash tools. Use when the user mentions logs, errors or time ranges.
---

## Instructions

1. Ask which log file and time range to inspect.
2. Use bash tools to filter:
   - `grep` for errors
   - `awk` to narrow by time
3. Only send small, relevant snippets back into the chat.
4. Summarize what you found and suggest next checks.

Claude can then run commands like:

grep "ERROR 500" /var/log/app.log | head -n 200

The big work happens in bash; the model only sees what matters. Your context stays clean and small.

With MCP, you often run a server that feeds extra structure and metadata into the model. That’s great for some integrations, but it’s overkill when your ask is as simple as, “Search these logs and tell me what’s going on.” Skills + bash give you that without blowing up tokens.

3. Short description, deep details (only when needed)

Each Skill starts with a tiny YAML header, something like:

---
name: pdf-helper
description: Work with PDF files (extract text, fill forms, merge documents). Use when the user mentions PDFs or document extraction.
---

Claude scans that description first. It’s short and clear, and it tells the model when to use the Skill. The rest — the long how‑to, edge cases, and examples — is only pulled in when the Skill is actually in use. Your everyday prompts stay light; you aren’t drowning the model in your whole company playbook on every message; and when the Skill is active you still get rich, detailed instructions. MCP tools often carry more structure up front (schemas, endpoints, parameters). That’s perfect for some integrations, but it adds context overhead. Skills keep the entry point tiny and go deep only when needed.

Supporting files: reference.md, examples.md, checklists.md

SKILL.md is the entry point: a short description and the core instructions. Supporting files like reference.md, examples.md, and checklists.md live next to it and hold deeper details. Claude will typically start with SKILL.md, then open these supporting files only when needed — a form of progressive disclosure that keeps context small until more depth is actually useful.

How this plays out in practice: your message triggers a scan of Skill descriptions, Claude chooses the relevant Skill, loads SKILL.md, and follows the steps. When the instructions reference extra material — for example, "See reference.md for error code details" — Claude can open that file and pull in just the relevant sections.

Only SKILL.md is special by name. Other markdown files (reference.md, examples.md, patterns.md, checklists.md, or any other .md/text file) are conventions — useful, but not “magical.” They become effective when SKILL.md points to them and explains when/why to consult them. If you drop foo.md into the folder and never reference it, it’s essentially invisible.

What belongs where:

  • Keep SKILL.md lean: what the Skill does, when to use it, a clear step‑by‑step flow, and maybe one or two short examples.
  • Put the heavy bits in reference.md: long checklists, policy/SOP text, large tables (error codes, status mappings), deep‑dive explanations, and team‑specific rules that would clutter the main instructions.
  • Use examples.md for runnable or copy‑pasteable examples that would distract from the main flow.
  • Use checklists.md for operational sequences you want to track explicitly (e.g., preflight checks, rollback steps).
  • Consider patterns.md or heuristics.md for debugging trees, decision guides, and “when X, try Y” patterns.

A scalable layout might look like this:

my-skill/
  SKILL.md
  resources/
    reference.md
    examples.md
    patterns.md
    checklist.md
  templates/
    summary.md

And in SKILL.md, make the references explicit so Claude knows when to load them:

For troubleshooting, see resources/troubleshooting.md.
For concrete usage examples, see resources/examples.md.
For patterns and heuristics, see resources/patterns.md.

Simple rules of thumb:

  • If it’s long or rarely needed, move it out of SKILL.md.
  • Mention supporting files explicitly in SKILL.md so Claude knows when to consult them.
  • Use clear headings in supporting files so Claude (and humans) can skim and extract the right section.
  • Don’t worry about size — these files are only read when the Skill is in use.

4. Skills are just files. Sharing them is easy.

This might be my favorite property: a Skill is just a folder in your repo. Skills are commonly placed under .claude/skills/ in your project (sometimes inside a tool‑specific subfolder). In some environments, these may also be mirrored under ~/.claude/skills at runtime — the important part is that they live alongside your code so they can be versioned and shared.

.claude/skills/

A typical layout might look like this:

.claude/
  skills/
    deploy-staging/
      SKILL.md
      scripts/
        deploy-staging.sh
        smoke-tests.sh
    log-investigator/
      SKILL.md

Commit Skills like any other code:

git add .claude/skills
git commit -m "Add deploy and log skills"
git push

Your teammates pull the repo, open it in Claude Code, and they have the same Skills you do. No servers, service accounts, or extra infra — just files. You can review Skills in PRs, version them, and copy them across projects. MCP servers are great when you need them, but they require someone to host, maintain, wire into each client, and manage auth and permissions — a lot of ceremony for what often boils down to running a few scripts and following a checklist.

Why Skills often beat MCP (for everyday work)

MCP shines when you need live access to external systems, one server shared across many clients, or strict control and monitoring. But most day‑to‑day work in Claude Code looks like cleaning a CSV, skimming logs to find what broke, guiding a release and running the right commands, or explaining how code reviews work in your team. For that, Skills are simpler (no server or protocol), cheaper (less context bloat, more work in bash), easier to share (git pull and you’re done), and closer to how developers already work (scripts, docs, and examples in the repo). If you already live in your editor and terminal, Skills feel like a natural extension — not a new platform to build. For a deeper dive on tool bloat, see “MCP Overload: Why Your LLM Agent Doesn’t Need 20 Tools”.

Some Skill ideas you can steal

Here are four concrete Skills you could build today:

1. Release checklist

Capture your release steps, run deploy and rollback scripts, and post notes to Slack. The result is consistent releases even when the team is tired. If reliability is your priority, you may also like “Why Prompt QA Matters More Than Model Tuning for LLMs” and “Stop Shipping Broken Prompts: A Guide to Prompt Testing”.

2. CSV cleanup

Lean on xsv, awk, or csvkit to clean data and send only small, clean samples back to Claude for analysis. You avoid dumping giant CSVs into the model while still getting smart help and summaries.

3. How we work

Describe branching rules, review expectations, and testing norms, with links to the right docs. New teammates can ask, “How should I do X here?” and get an answer that reflects your actual process. If you’re thinking about how to frame prompts and workflows, see “Prompting Is Onboarding: Why LLMs Need Structure, Not Spells”.

4. Logs and incidents

Point to where logs live, outline common error patterns, and suggest commands to run during an incident. When something is on fire, Claude doesn’t just explain — it helps you poke at the logs.

Try it: your first Skill in 5 minutes

If you want to see the magic for yourself, start tiny.

  1. Create a folder:

    mkdir -p .claude/skills/release-checklist

  2. Add a SKILL.md:

    ---
name: release-checklist
description: Guide and execute our standard release checklist. Use when the user mentions releasing a new version.
---

# Release Checklist

1. Run tests: `./scripts/run-tests.sh`.
2. Build and tag the release.
3. Deploy to staging.
4. Run smoke tests.
5. Deploy to production.
6. Post a summary in #releases.

  3. Open your repo in Claude Code.

  4. Say: "Help me run our release-checklist skill for this branch."

Claude should notice the description, pick up the Skill, and walk you through it.

Packaging and testing (optional)

If you plan to distribute or upload a Skill, keep the folder self‑contained with SKILL.md at the root and any resources/scripts in subfolders. Package it as a ZIP with the Skill folder as the root, not loose files. Before sharing, review the description for clarity (it drives invocation), verify referenced files exist, and test with prompts that should trigger the Skill. As you iterate, update version to track changes. Claude can compose multiple Skills automatically when appropriate, and you should avoid hard‑coding secrets in scripts or docs.

Tip: to jump‑start a new Skill, check out Anthropic’s open‑source Skill Creator, which scaffolds a Skill folder (including Skill.md/SKILL.md and resources) you can adapt to your workflow — see Anthropic’s Skill Creator.

Wrap-up

Skills in Claude Code are small, file‑based, bash‑friendly, and easy to share. They let you explain how something should be done and automate actually doing it — without spinning up an MCP server, maintaining extra infra, or blowing up your context.

Use MCP when you truly need deep integration with external systems. For most everyday coding, debugging, and shipping, Skills offer a lighter, faster, and far more pleasant way to put AI to work. And the best part? You don’t need a platform to get started — just a folder, a markdown file, and a couple of scripts you already have lying around.