The Specific Situation

You need Claude Code to interact with your company’s internal Jira instance – create tickets, update statuses, query sprint boards. You could write a SKILL.md that tells Claude how to use the Jira API via curl commands. Or you could set up an MCP server that exposes Jira operations as tools. Both work, but they solve fundamentally different problems. Choosing wrong means rebuilding later.

Technical Foundation

Skills are markdown instruction files (SKILL.md) that tell Claude what to do and how. They load into the conversation as context. Claude follows the instructions using its existing tools (Bash, Read, Grep, etc.). Skills are text files with no runtime component – they are instructions, not executables.

MCP servers (Model Context Protocol) are running processes that expose new tools, resources, or prompts to Claude. They add capabilities Claude does not have natively. An MCP server for Jira would expose jira_create_issue, jira_list_sprints, etc. as new tools Claude can call.

The key architectural difference: skills tell Claude HOW to use existing tools. MCP servers give Claude NEW tools.

The Working SKILL.md (Jira via Skills)

---
name: jira-ticket
description: >
  Create and update Jira tickets using the REST API. Use when the
  user says "create a ticket", "update Jira", or "log this issue".
disable-model-invocation: true
argument-hint: "[action] [details]"
allowed-tools: Bash(curl *)
---

# Jira Ticket Management

Manage Jira tickets via REST API.

## Create a Ticket

```bash
curl -s -X POST \
  -H "Authorization: Bearer $JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"project":{"key":"PROJ"},"summary":"TITLE","issuetype":{"name":"Task"}}}' \
  https://your-domain.atlassian.net/rest/api/3/issue

Update Status

curl -s -X POST \
  -H "Authorization: Bearer $JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transition":{"id":"STATUS_ID"}}' \
  https://your-domain.atlassian.net/rest/api/3/issue/ISSUE_KEY/transitions

Replace PROJ, TITLE, STATUS_ID, and ISSUE_KEY with actual values from $ARGUMENTS.


## When Skills Are the Right Choice

| Scenario | Why Skills Win |
|----------|---------------|
| Codifying a workflow | Skills encode step-by-step procedures as instructions |
| Enforcing conventions | "When writing API endpoints, always..." |
| Teaching Claude about your codebase | Reference docs loaded on demand |
| Simple CLI tool wrapping | `curl`, `gh`, `aws cli` already available via Bash |
| Quick iteration | Edit a text file, changes detected live |
| Team distribution | Commit `.claude/skills/` to git, done |

## When MCP Servers Are the Right Choice

| Scenario | Why MCP Wins |
|----------|-------------|
| Authenticated API access | Server handles token refresh, OAuth flows |
| Complex data transformation | Server-side logic for parsing, filtering |
| Stateful operations | Server maintains connections, caches, sessions |
| Type-safe tool interfaces | Server defines input/output schemas |
| External service with SDK | Use the official SDK instead of raw curl |
| Multi-step transactions | Server handles rollback on failure |

## When to Combine Both

The most effective pattern uses both together. An MCP server provides the tools (authenticated Jira access), and a skill provides the workflow instructions (how to use those tools in your team's process):

```yaml
---
name: sprint-planning
description: >
  Run sprint planning workflow using Jira MCP tools. Use when
  the user says "plan the sprint" or "organize next sprint".
disable-model-invocation: true
---

# Sprint Planning Workflow

Use the Jira MCP tools for all Jira operations.

1. Query current backlog: use jira_search with JQL
   `project = PROJ AND status = Backlog ORDER BY priority`
2. Get team velocity: use jira_get_board to check last sprint
3. Select stories up to velocity cap
4. Move selected stories to sprint: use jira_move_to_sprint
5. Assign stories based on expertise tags

## Rules
- Never exceed 80% of average velocity
- Every sprint must include at least one tech debt item
- Block any story without acceptance criteria

Common Problems and Fixes

Skill approach fails with OAuth: Skills can only use tools Claude already has. If the API requires OAuth token refresh, complex header management, or session cookies, use an MCP server that handles auth internally.

MCP server is overkill for simple tasks: If you are wrapping a CLI tool with straightforward arguments (gh pr create, aws s3 ls), a skill with allowed-tools: Bash(gh *) is faster to create and maintain than an MCP server.

Both installed but conflicting: Skills and MCP tools coexist. If a skill tells Claude to use curl for Jira but an MCP server also exposes jira_* tools, Claude may use either. Specify which approach to use in the skill body: “Use the Jira MCP tools, not curl.”

MCP server not discovered: MCP servers are configured in Claude Code settings, not in .claude/skills/. They are separate systems. A skill cannot install or start an MCP server.

Production Gotchas

Skills follow the Agent Skills open standard (agentskills.io) and work across multiple AI tools. MCP servers follow the Model Context Protocol standard and also work across multiple clients. If portability across AI tools matters, both approaches are standards-based.

Skills have zero startup cost (text files loaded on demand). MCP servers require a running process. In CI/CD environments, starting MCP servers adds complexity and latency.

Skills are limited by what Claude can do with its existing tools. If Bash, Read, Grep, and Glob cannot accomplish the task, you need an MCP server to provide new capabilities. The boundary question is simple: does Claude need a new tool, or does it need instructions for using existing tools?

Checklist