Skip to content
Get packs

Guide · Agent skill

How to use the Atlassian MCP Expert agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The atlassian-mcp skill is a set of instructions that gives an AI agent specialist knowledge of Atlassian tools, mainly Jira (issue tracking) and Confluence (team wiki). Once it is installed, the agent knows how to write Jira Query Language (JQL) and Confluence Query Language (CQL) searches, create and update tickets, manage sprints and backlogs, and connect to Atlassian through the Model Context Protocol (MCP). This guide covers what the skill does, how to install it, how to trigger it, what it needs, and the safety points to check before letting an agent change data.

Atlassian MCP ExpertJeffallan/claude-skills · MIT

Quick start

  1. 1Download the ZIP. Get the atlassian-mcp skill ZIP from its page in this directory.
  2. 2Unzip the skill. Extract the folder so that SKILL.md sits inside a folder named atlassian-mcp.
  3. 3Place the folder. Copy it to ~/.claude/skills/ for personal use, or to .claude/skills/ in a project. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  4. 4Connect to Atlassian. For Cloud, add the hosted MCP server and run /mcp to sign in with OAuth. For Server or Data Center, configure mcp-atlassian with your personal tokens in environment variables.
  5. 5Make a request. Ask in plain language, naming the project or space, and mention Jira, Confluence or JQL/CQL.
  6. 6Test with one result. Ask the agent to validate the query with maxResults=1 before running a full search or any change.

What an agent skill is and what this one changes

An agent skill is a folder containing a SKILL.md file and optional reference documents. Your agent reads these when a request matches the skill's description, so it can follow specialised guidance without you pasting that guidance into every chat.

Model Context Protocol (MCP) is a standard way for AI tools to reach outside services. The atlassian-mcp skill does not replace an MCP connection; it teaches the agent how to use one well for Atlassian products.

  • Writes JQL filters for Jira issues, such as searching by project, status, assignee or date
  • Writes CQL searches for Confluence pages, such as searching by space, type or text
  • Creates and updates tickets, including custom fields
  • Manages sprints and backlogs
  • Sets up MCP server authentication and explains the options
  • Helps debug Atlassian API integrations

Install the atlassian-mcp skill

Download the skill ZIP from the skill's page in this directory and unzip it. For a personal install, place the folder in ~/.claude/skills/. To share it with one project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/ (available across your projects)
  • Project: .claude/skills/ inside the project folder (shared with that project)
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Connect Atlassian before you ask for queries

The skill assumes a working MCP connection. Which setup you need depends on your Atlassian product. For Atlassian Cloud, connect to the hosted Atlassian Rovo MCP Server and sign in with OAuth using the /mcp command. For Jira or Confluence Server or Data Center, run the community mcp-atlassian server with personal access tokens.

Keep tokens in environment variables or a secrets manager. The skill says never to hardcode credentials in configuration or code.

  • Atlassian Cloud: OAuth sign-in through /mcp
  • Server or Data Center: uvx running mcp-atlassian, with JIRA_PERSONAL_TOKEN and CONFLUENCE_PERSONAL_TOKEN set as environment variables (or equivalent secrets)
  • Read references/mcp-server-setup.md for tool names, which differ between servers
claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp

Trigger the skill with natural requests

You do not need a special command. Describe the Atlassian task in plain language and mention Jira, Confluence, a sprint, JQL, CQL or MCP. The skill's trigger words include Jira, Confluence, Atlassian, tickets, issues, wiki, sprint and backlog.

Ask for a read-only result first when you are unsure. The skill's workflow tests queries with maxResults=1 before running a full search.

  • "Using Atlassian, list open bugs in project PROJ created in the last 7 days."
  • "Write a JQL query for my unfinished issues in the current sprint, then test it with one result."
  • "Find Confluence pages in the ENG space updated this year that mention deployment runbook."
  • "Why is my Atlassian MCP login failing? Walk me through the authentication options."

Understand the query examples

JQL searches Jira issues. The skill includes examples such as open issues assigned to the current user in a sprint, and unresolved bugs created in the last seven days. CQL searches Confluence content, for example pages in a space that contain a phrase, or pages updated since a date.

project = PROJ AND issuetype = Bug AND status != Done AND created >= -7d ORDER BY created DESC space = "ENG" AND type = page AND text ~ "deployment runbook"

Stay safe with scripts, network access and credentials

This skill does not run scripts, but it does use the network, because its purpose is to call Atlassian services. It needs credentials: OAuth sign-in for Cloud, or personal access tokens for Server and Data Center. Only use it where your organisation has approved OAuth or API token use.

The skill's rules say to respect user permissions, confirm before any write or bulk operation against production data, log API calls for audit, and avoid exposing sensitive issue data in logs or error messages. Check permission scopes with a read-only probe before any change.

  • Confirm before writes or bulk edits, and review the proposed changes
  • Use a test project or a small query before touching production data
  • Do not paste tokens into chat or commit them to code
  • If a request is ambiguous, a wrong instruction could still change many records if confirmation is skipped

Tips for better results

Name the product, project key and space in your request so the agent picks the right server and query. If a tool call fails, give the agent the error message and ask it to check authentication and permissions, which the skill covers.

For self-hosted setups, check the tool names in the server setup reference before writing automation, because they vary between servers.

  • Include the project key (for example PROJ) and space key (for example ENG)
  • Ask for pagination in large results; the skill suggests 50 to 100 items per page
  • Ask the agent to explain each query so you can check it before running it

What people use it for

  • Pull open bugs or unfinished sprint work from a Jira project using JQL
  • Find Confluence pages in a space by text, type or last-updated date using CQL
  • Plan sprint and backlog changes, with confirmation before edits
  • Set up an MCP connection for Claude Code and check that permissions are correct
  • Debug a failing Atlassian API or authentication setup

Frequently asked questions

Is the atlassian-mcp skill free to use?

The skill is published under the MIT licence. Atlassian's own products and accounts are separate, and you need an Atlassian account with the access you require. Check your organisation's Atlassian plan for any costs.

What do I need to use the atlassian-mcp skill?

You need an Atlassian Cloud account with OAuth sign-in, or Jira and Confluence Server or Data Center with personal access tokens. You also need Claude Code or another MCP-capable agent. For self-hosted setups you need uv/uvx to run the community mcp-atlassian server.

Where do I put the atlassian-mcp skill folder?

Place it in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder to share it with that project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.

Does the skill run scripts on my computer?

No, the skill is listed as not running scripts. It does use the network, because it calls Atlassian services through an MCP connection.

Why is my Atlassian MCP connection failing?

Ask the agent to check authentication and permissions. Confirm you have signed in with OAuth for Cloud, or that your personal access tokens are set in environment variables for Server or Data Center. The skill's reference on authentication patterns covers the options.

How does this compare with using Jira or Confluence directly?

If you only need to read a few tickets, opening them manually is simpler, because setup adds complexity for little gain. The skill is more useful when you want an agent to run precise JQL or CQL searches, or to manage many tickets, with confirmation before changes.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a developer or project manager who wants an agent to run precise Jira or Confluence queries, or an engineer debugging an Atlassian MCP setup. Skip it if you only need a few tickets, or if your organisation has not approved OAuth or API token use, since the skill requires storing credentials.

Download the skill