atlassian-skill
Read-only access to Atlassian Jira and Confluence via MCP. Use for reading Jira issues/tickets and Confluence pages/documentation, including daily page diffs. Triggers on mentions of Jira, Confluence, Atlassian, Jira issue, Jira ticket, Confluence page, Confluence space, daily doc sync, page diff, or page history.
- License 许可
- BSD-3-Clause
- 所属仓库
- kalaverin/skills
- 最近更新
- 2026-11-15
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- atlassian-skill
- runtime
- true
- version
- 0.1.0
- triggers
- { "reason": "User needs to read Jira issues or Confluence pages.", "request": "jira, confluence, atlassian, issue, ticket, epic, jira issue, jira task, confluence page, confluence space, confluence doc, daily doc sync, page diff, page history, джира, жира, задача в джира, тикет, конфла, конфлюенс, страница конфлюенс" }
- description
- Read-only access to Atlassian Jira and Confluence via MCP. Use for reading Jira issues/tickets and Confluence pages/documentation, including daily page diffs. Triggers on mentions of Jira, Confluence, Atlassian, Jira issue, Jira ticket, Confluence page, Confluence space, daily doc sync, page diff, or page history.
02 资源文件 1
- 参考文档README.md3.9 KB
03 SKILL.md 正文
SKILL: Atlassian Reader (Jira + Confluence)
Read-only skill for Atlassian Cloud and Data Center. Covers Jira issue search/reading and Confluence page search/reading, including daily diff/history sync. Never writes or mutates Atlassian data.
Allowed tools
[ref: #atlassian-allowed-tools]
This skill is read-only. Use only the tools listed below. Never call any tool that creates, updates, transitions, deletes, or writes Atlassian data. If the user asks for a read operation not listed here, confirm before using another read-only tool.
Jira
jira_search— search issues via JQL.jira_get_issue— read one issue with comments, worklogs, and links.jira_get_project_issues— list issues in a project.jira_get_all_projects/jira_search_projects— find projects.jira_get_user_profile— resolve a Jira user.
Confluence
confluence_search— CQL or text search for pages.confluence_get_page— read a page by ID or title+space.confluence_get_page_children— child pages and folders.confluence_get_space_page_tree— full space hierarchy.confluence_get_page_history— previous versions.confluence_get_page_diff— diff between two versions.confluence_search_user— resolve a Confluence user.
Hard parameter rules
[ref: #atlassian-hard-parameter-rules]
Confluence
| Parameter | Rule |
|---|---|
convert_to_markdown |
Always true. Returning storage-XHTML kills the session. Hard rule. |
include_content |
Always false for confluence_get_page_children and confluence_get_space_page_tree. Bodies are not needed for navigation. |
include_metadata |
Default false for confluence_get_page when only page text is needed. Set true when reading version or history.lastUpdated for actualization. |
limit |
Search — 3–5; children — 5–10; space tree — 10–20. |
spaces_filter |
Use when the space key is known. |
Jira
| Parameter | Rule |
|---|---|
fields |
Always pass a concrete list like summary,status,assignee,labels. Never *all. |
comment_limit |
For jira_get_issue: default 0. Read comments only if the user explicitly asks. |
limit |
Search — 3–5, max 10; project issues — 5–10. |
expand |
renderedFields is forbidden in any form. HTML in responses is not allowed. |
include |
Never use include=all. Request only explicitly needed sections. |
use_display_names |
Default false; true inflates the response. |
Jira issue key format
[ref: #atlassian-jira-issue-key-format]
Jira issue keys are always uppercase.
- Normalize any user-supplied key to uppercase before calling Jira tools.
- Valid format:
[A-Z][A-Z0-9_]+-\d+(for examplePROJECT-123,TEAM42-7,MY_PROJECT-99). - Never pass a mixed-case or lowercase key such as
Wgnbck-5314; convert it toWGNBCK-5314first. - This rule is hard: a lowercase key fails validation before the tool call.
External source versioning
[ref: #atlassian-external-source-versioning]
When the agent saves a local copy of an Atlassian artifact, it stores the file under .serena/memories/atlassian/<kind>/<id>.md and adds an external_source block to the frontmatter. Later "update" / "actualize" requests use this block to fetch only the delta instead of pulling the whole document. This custom artifact scope is owned by the Atlassian skill and does not violate serena-protocol.
Confluence example:
external_source:
atlassian:
kind: confluence
id: 1501236
version: 41
last_sync_at: 2025-06-17T00:00:00Z
Jira example:
external_source:
atlassian:
kind: jira
id: WGNBCK-5314
updated_at: 2025-06-17T00:00:00Z
last_sync_at: 2025-06-17T00:00:00Z
kind—confluenceorjira.id— for Confluence the numeric page ID; for Jira the uppercase issue key.version— Confluence page version number fromhistory. Not used for Jira issues.updated_at— Jira issueupdatedfield. Not used for Confluence pages.last_sync_at— UTC timestamp of the last successful sync of this local copy.
If the block is missing or incomplete, fall back to a full read.
Pagination
Use start/start_at/page_token instead of pulling large lists at once.
Workflows
[ref: #atlassian-workflows]
If a search returns several equally plausible results, ask the user which one to read instead of fetching multiple pages or issues.
Read a Jira issue
- If you have the issue key, normalize it to uppercase (
Wgnbck-5314→WGNBCK-5314). - Call
jira_get_issue(issue_key=..., fields="updated", comment_limit=0)to check freshness. - If a tracked local copy exists with
external_source.atlassian.kind=jira, matchingid, andupdated_atequal to the returnedupdated, return the local summary. - Otherwise call
jira_get_issuewithfields="summary,status,assignee,labels,description,updated"andcomment_limit=0. - Summarize: summary, status, assignee, description, labels. Omit comments unless asked.
- When saving a local copy, stamp
external_source.atlassian.kind=jira,id,updated_at, andlast_sync_atunder.serena/memories/atlassian/jira/<id>.md.
Actualize a Jira issue
[ref: #atlassian-workflow-actualize-jira]
- Load the local copy from
.serena/memories/atlassian/jira/<id>.mdand readexternal_source.atlassian.idandexternal_source.atlassian.updated_at. Requirekind=jira. - If missing, fall back to Read a Jira issue.
- Normalize the key to uppercase.
- Call
jira_get_issue(issue_key=..., fields="updated", comment_limit=0). - If returned
updatedequals recordedupdated_at, report "no changes" and stop. - Call
jira_get_issue(issue_key=..., fields="summary,status,assignee,labels,description,updated", comment_limit=0). - Summarize changes, update the local copy, and bump
external_source.atlassian.updated_atandexternal_source.atlassian.last_sync_at.
Read project tasks
- Use
jira_search_projectsorjira_get_all_projectsto find the project key. - Use
jira_get_project_issuesorjira_searchwithproject = KEY, limitedfields, andlimit.
Read Confluence documentation
- Look for a tracked local copy under
.serena/memories/atlassian/confluence/<page_id>.mdwithexternal_source.atlassian.kind=confluence. If it exists, read itsidandversion; otherwise useconfluence_searchwith a narrow CQL query andlimit=3–5to find the page. - Use
confluence_get_page(page_id=..., include_metadata=false)to read the page body. - When saving a local copy, write it to
.serena/memories/atlassian/confluence/<page_id>.mdand stampexternal_source.atlassian.kind=confluence,id,version, andlast_sync_atfromhistory. - For navigation, use
confluence_get_page_children(..., include_content=false, limit=5–10)orconfluence_get_space_page_tree(..., limit=10–20).
Actualize a Confluence page
[ref: #atlassian-workflow-actualize-confluence]
- Load the local copy and read
external_source.atlassian.idandexternal_source.atlassian.version. Requirekind=confluence. - If missing, fall back to Read Confluence documentation.
- Call
confluence_get_page(page_id=..., include_metadata=true)to read current version andhistory.lastUpdated. - If current version equals recorded
version, report "no changes" and stop. - Call
confluence_get_page_diff(page_id=..., from_version=recorded, to_version=current). - If the diff call fails (404, version not in history, etc.), hard stop and ask the user how to proceed.
- Summarize the diff, update the local copy, and bump
external_source.atlassian.versionandexternal_source.atlassian.last_sync_at.
Daily documentation sync
- Scan
.serena/memories/atlassian/confluence/for files withexternal_source.atlassian.kind=confluence. - For each tracked page, read
external_source.atlassian.idandexternal_source.atlassian.version. - Call
confluence_get_page_history(page_id=..., limit=...)to list versions newer than the recorded one. - If no newer versions exist, skip the page.
- Otherwise call
confluence_get_page_diff(page_id=..., from_version=recorded, to_version=newest). - Summarize changes, update the local copy, and bump
external_source.atlassian.versionandexternal_source.atlassian.last_sync_at. - For pages without a tracked version, fall back to diffing the last 24 hours.
Oversized response hard stop
[ref: #atlassian-oversized-response-hard-stop]
When you receive an MCP tool result, check its character length before processing. If it exceeds ~100 000 characters or consumes most of the available context:
- Hard stop. Do not read further, summarize, save, or continue.
- Report to the user: the tool called, the arguments used, and the approximate response size.
- Wait for user instructions.
The raw response is already in context — any continuation makes it worse.
Error handling
[ref: #atlassian-error-handling]
| Error | Meaning | Action |
|---|---|---|
401 Unauthorized / 403 Forbidden |
Credentials or permissions problem. | Hard stop. Ask the user to check credentials. No retries. |
404 Not Found |
Issue or page does not exist, or wrong key/ID. | Check the key case and normalize to uppercase; verify the key/ID/space with the user or the source. Do not retry until corrected. |
| Empty search results | Query too narrow or wrong space/project. | Check CQL/JQL and filters. |
Confluence client not available / Jira client not available |
MCP server did not initialize the client. | Hard stop, report to the user. |
| Oversized response | Response >~100K characters. | See ## Oversized response hard stop. |
Context protection
[ref: #atlassian-context-protection]
- Always start with
confluence_search/jira_searchwith a tightlimit. convert_to_markdown=true;include_content=falsealways for children and space tree;include_metadata=falseby default for page reads; settruewhen actualizing to readversionandhistory.lastUpdated.- Never download attachments or images unless explicitly asked.
- Never request HTML;
renderedFieldsandconvert_to_markdown=falseare forbidden. - For Jira, always pass
fieldsandcomment_limit=0by default. - Do not keep raw JSON in context: summarize relevant facts and discard the original response.
- Do not pull several large pages/issues into the same turn.
- Daily sync: read diffs, not full pages.
04 同仓库更多 Skills
todo-protocol
Mandatory protocol for using the SetTodoList tool. Governs when to create a todo list, how to update it without violating immutability rules, how to synchronize item status after every tool call, and the forbidden mutations. Always active.
subagents-protocol
Mandatory protocol for delegating work to built-in subagents (coder, explore, plan), also called our bots by users. Always active. Owns the context-hygiene delegation test (material vs answer, cost balance, warm-instance reuse), launch parameters (mandatory explicit `model`), the single-source model-selection table, answer budgets, degradation handling, the launch checklist, and the role library for delegated review/audit with intent routing (`references/roles.md`).
serena-protocol
MANDATORY skill for Serena (MCP) memory, knowledge base, and symbolic code exploration operations. Use whenever the agent needs to: read or write Serena memories, mutate or persist memory, explore code via symbolic MCP tools, resolve contradictions in stored knowledge, or follow memory metadata, naming, and routing conventions.
read-for-comments
Mandatory local standards library and archive. Before fetching any standard from the internet, the agent MUST check the Serena `standard/` archive and this skill's `references/` seed; after ANY standard-body download, the agent MUST archive it per the event-bound Archival Rule. Governs standard lookup, fetch, archival, and the family and full-body rules.
python-lang
MANDATORY skill for Python code. Use when writing, editing, refactoring, or reviewing Python files, modules, packages, classes, functions, type annotations, imports, exceptions, comprehensions, decorators, or docstrings. Enforces Google Python Style Guide and a mandatory, unconditional Ruff format+check pipeline scoped strictly to the agent's own changes.
preflight-checklist
Mandatory session-initialization closer and Startup Gate audit. Always loaded. Runs EXACTLY ONCE at session start, after all skill loading completes: verifies Startup Gate completion with evidence (mirror sync, forced import, discovery, activation, memory priming, MCP declaration, think block), runs dynamic session checks derived from the active skill set (mode states, delegation readiness), and reports a compact evidence-backed verdict table to the user before the first task output. Any FAIL is fixed before proceeding.