This is the shared method every skill in this repo uses to gather context and deliver its result. A skill loads it first, then adds what’s specific to its job: the anchor, the sources it needs, what the artifact shows and when to stop. Where a skill and this file disagree, the skill wins.
Companion skills mentioned as alternatives or next steps are optional. Check that a suggested skill is installed before offering its slash command. If it is unavailable, describe the next step in ordinary language and use the current host’s available capabilities.
Searches surface whatever the user can see, and that includes documents nobody wants in a status report. This rule overrides every skill.
/archives/D. A group message’s channel name starts with mpdm-. A channel whose name says leadership, exec, staff or board, or uses a word or abbreviation for them (leaders, leads, lt, elt, slt), counts as exec-only material whether or not it’s private, since search results don’t show a channel’s privacy.title="" attributes.These are the operation names on version 2 of the Atlassian Rovo MCP server, the only version these skills support (version 1 is being deprecated). Clients prefix them with the connector’s name (for example mcp__atlassian__search). Connect it using the current agent host’s documented MCP setup. Access to tools in a conversation does not imply access from an artifact; check the host’s live-artifact capabilities separately (see “Live artifact”).
| Tool | Use it to | Know this |
|---|---|---|
getGraphContext |
Walk from one object to everything linked to it, across Atlassian and connected tools, in one call. Filter with relationshipTypes, targetObjectTypes and timeRange. |
Direction is only in the relationship name, and same-type names don’t all read the same way. Some links are missing or one-sided, and Atlas project and goal keys don’t resolve. See “What the graph doesn’t tell you”. |
getGraphObject |
Read full detail for up to 25 objects at once by ARI or URL. | Full for Atlassian objects and Google Drive docs. Often empty (raw: {}) for GitHub, and refused for Slack. Bitbucket pull requests hydrate when passed by the graph ARI (state, approvals, description cut at about 1,000 characters), though bitbucket.org URLs don’t resolve. Confluence pages come back as raw ADF, which can be huge: use getConfluenceContent instead. |
search |
Find things the graph hasn’t linked. | See “Searching”. |
getWorkActivity |
What a person or up to 10 people did, were assigned or were mentioned in, across Jira, PRs, docs, goals, calendar and video, over a time window. | Use countsOnly when you only need the volume. topic can’t be combined with identifiers. With identifiers, trust each item’s ok over the batch summary, which can count partial coverage as a failure. |
getWorkPortfolio |
Projects, goals and focus areas for people, with status. | Large by default, because it includes direct reports. Pass includeDirectReports: false unless you need the org, and use kinds, view: compact and limitPerCollection. includeInferredProjects can return SOURCE_FAILURE. If it does, record the gap and move on. |
getPeopleInfo |
Profiles, managers and direct reports. | manager: true gives the escalation contact in the same call. Profiles carry a department but no team: take a person’s team from the project or work record that names them. |
getCollaborators |
Who someone works with most. | |
searchCode, getCodeFile, scanCodeRepo, listCodeDirectory |
Search code across connected Bitbucket and GitHub repos (mode hybrid, semantic or lexical, filtered by namespace, repo, path, language), then read a file, list a repo’s paths or browse a directory at a commit. |
Reached through discover and run with executeRead, only when code-search is in the site’s products list. Pass a result’s own workspace, repo, path and version (as commitHash) to the reads, never the search filter. Results are noisy and getCodeFile has no line numbers: see “Code and repositories”. |
Use these for structured facts, and for detail the graph doesn’t carry:
| Need | Tool |
|---|---|
| A goal’s projects, sub-goals, metric targets, updates and highlights | getGoal |
| A project’s dependencies, links, teams, updates and highlights | getProject, getProjectUpdate |
| Jira issue links with direction | getJiraIssue with view: evidence (issuelinks[].inwardIssue and outwardIssue) |
| A Jira issue’s web links to pages and URLs | listJiraIssueRemoteIssueLinks |
| When a Jira field changed (status, assignee) | listJiraIssueChangelogs |
| Lists of Jira work by structured criteria | searchJiraIssuesUsingJql |
| A Confluence page body | getConfluenceContent with content_format: markdown and detail: full (the default is a short excerpt) |
| A Loom transcript or AI action items | getLoomVideo |
| Release approvers, capacity, teams | getJiraProjectVersions, getCapacityPlanAllocations, searchTeams |
| A board’s sprints and columns, and a sprint’s issues | getJiraBoardSprintData, getJiraBoardConfig (through discover) |
getGoal and getProject return 5 items per connection (projects, updates, dependencies, highlights and so on) unless you pass limits (up to 20 each). Set limits for every connection you include, and page while hasNextPage is true. A silently truncated list is a wrong answer. The one exception is updates: the latest 5 are enough unless you need older history.fields: ["summary", "status", "created", "project"] and maxResults of 25 to 50, then read descriptions only for the issues you’ll use.lostFeatures:
time: date elements (shown as date lozenges) disappear. On real data a decision register lost all 47 of its dates. Take each date from its <time datetime="…"> element in the HTML read.ac:structured-macro or ac:adf-extension: panels (panel-note, panel-custom) and macros can vanish whole. On real data a page’s “Decision” panel, which held the decision itself, was missing from the markdown, and a heading came back with nothing under it.When lostFeatures lists either, and the page matters to the answer (a decision, a plan, a spec), re-read it with content_format: html. Also re-read when a heading has nothing under it, or when a search snippet quotes text that isn’t in the markdown body. diffConfluenceContentVersions has the same gap: a markdown diff came back empty for a version that added that panel, so diff with content_format: html whenever the change you’re looking for could be in a panel or a date.
listLoomObjects returned 15 items per page, newest first, even with limit: 25, so one call over a long createdAtRange covers only its last week or two. List a narrow window around the dates that matter, and say in the footer what the list reached. To page, set createdAtRange.to to the oldest createdAt returned: nextOffset came back as 25 after a 15-item page, and following it skipped ten days of recordings. Each item’s description is usually the AI meeting summary, so list with responseFields set to titles, dates and URLs when the titles need a sensitive-content check first, then read the kept ones with one getLoomObjectsContent batch (up to 10, no expand), which returns description too. Its expand value is agentBrief (singular, unlike getLoomVideo’s agentBriefs), and it usually came back ABSENT.latestUserUpdate and its creationDate, not system-generated updates. Note missedUpdate: true when it’s set. A bot’s update can be typed USER too: see “Automation updates”.discover with a verb and object (“get goal updates”, “list sprint data”), then run it with the matching executeRead, executeWrite or executeDestructive. Pass cloudId as a top-level argument, never inside inputs. Never guess an operation name.getGraphContext returns and filters on underscore names. addGraphContext takes hyphenated names. Names seen so far:
Read with getGraphContext |
Write with addGraphContext |
|---|---|
jira_work_item_blocks_jira_work_item, jira_work_item_is_blocked_by_jira_work_item |
jira-work-item-blocks-jira-work-item |
jira_work_item_tracks_atlassian_project |
jira-work-item-tracks-atlassian-project |
jira_work_item_contributes_to_atlassian_goal |
jira-work-item-contributes-to-atlassian-goal |
jira_work_item_has_child_jira_work_item, jira_work_item_has_parent_jira_work_item |
(use the issue’s parent field) |
jira_work_item_links_jira_work_item_remote_link |
jira-work-item-links-jira-work-item-remote-link |
atlassian_project_depends_on_atlassian_project, atlassian_project_links_atlassian_project |
(use Projects) |
atlassian_project_contributes_to_atlassian_goal |
(use addConnectionsToGoals with type PROJECT) |
atlassian_project_has_atlassian_project_update |
|
atlassian_user_owns_atlassian_project, atlassian_user_contributes_to_atlassian_project |
Call getGraphContext with detailLevel: summary first to see which relationship types an object actually has, then filter the full call to the ones you need.
The client may also have connectors from the vendors themselves, such as Google Calendar, Gmail, Google Drive, Slack, GitHub, Microsoft 365 (Outlook, Teams, OneDrive) or Zoom. They show up in the session’s tool list under the app’s name. Teamwork Graph comes first, because it connects tools and a vendor connector only sees its own app. Always run the graph’s own search or read before reaching for a connector, even for an app that has one. Use a vendor connector only to fill a gap the graph has, and say in the footer which gap it filled:
| Gap in Teamwork Graph | Use the vendor connector to |
|---|---|
Lists by time. getWorkActivity windows on when a relationship last changed, recurring meetings have no daily instances, and search has no date filter. |
List a day’s calendar events. For email and chat, filter graph search results by lastModified first, and use the connector’s date operators (such as newer_than:1d or after:2026-10-18) only when that came back empty or too thin to trust. |
Third-party objects that won’t hydrate (Slack messages left out of getGraphObject, GitHub raw: {}, Drive docs with no body). |
Read the full thread, replies, pull request body and reviews, or doc, instead of settling for the search snippet. |
| Facts only the vendor holds. | Read RSVPs, recurrence and attendee lists for meetings, whole email threads, and file revision history. |
htmlLink encodes the calendar owner’s email address in its eid. Don’t use it as a smart link: name the event in plain text, or link the day view.search.getAccessibleAtlassianResources once per session and reuse the cloudId. Keep the site’s products list too: it says which Atlassian apps the user can use on the site (see “Atlassian apps on the site”).atlassianUserInfo once if the skill needs the current user’s account ID.getGraphContext, search and the people tools can each use Rovo credits, so keep calls bounded. Unless a skill sets its own budget, aim for no more than 10 search calls and 10 getGraphContext calls per run. If a call fails because credits are exhausted, tell the user and stop. Don’t retry.Most of a run’s time goes on calls made one after another. Before each step, list the calls whose inputs you already have, and send them together in one turn: lookups for each person, each candidate video or doc, each search phrasing, and reads of goals and projects already found. Wait only for the calls the next step needs. Calls that don’t depend on each other can run together even when they sit in different steps of a skill.
getGraphObject call for up to 25 objects beats 25 parallel calls. The same goes for one JQL key in (...) query, or getPeopleInfo with up to 10 account IDs.getProject call straight after a batch of 7 parallel calls returned 429 twice.mode: STANDARD with a targetApp. targetApp only filters in STANDARD mode: THIRD_PARTY for connected tools, JIRA, CONFLUENCE, or ALL. limit takes 10 to 30.targetApp, and they may be disabled for the site (“Agentic search is not enabled”, 403). If one fails, carry on with STANDARD and don’t mention it unless it changes coverage.lastModified after the search, and state the window in the footer. For a strict time window (“since yesterday”), filter the graph results first, and add the vendor connector’s own search where the client has one only if that isn’t enough (see “Vendor connectors”). Know what the date means per source: GitHub’s is last updated, not opened, and a page’s is last edited, not written. If a strong hit falls just outside the window, mention it in the footer rather than dropping it silently.updated >= "2026-10-06", status CHANGED DURING (…), resolved >=), CQL through searchConfluence (lastmodified >= "2026-10-06" and created >= filter the window reliably, but results carry only relative lastModified text such as “about 4 hours ago”, and expand is ignored, so mark pages as new with a separate created >= query and take exact edit dates from listConfluenceContentVersions), getProject with updateFilters, listLoomObjects with createdAtRange, and getPullRequests with updatedSince or mergedSince. Keep JQL CHANGED clauses beside a project = or assignee = clause: across a whole site they can time out. Use search for what the records don’t hold, and filter it by lastModified.search with targetApp: JIRA for fuzzy discovery only.text ~ "Atlassian MCP" matches either word, and text also searches comments. For a phrase, quote it inside the string (text ~ "\"Atlassian MCP\""). For precision, use summary ~ and description ~ once you know the project.getConfluenceContent.For a skill that covers a window (“since the last update”, “while I was away”), each item gets one event time, the moment the thing happened, from this table. An item is in the window only if its event time is.
| Source | Event time |
|---|---|
| Jira status, assignee, due date or priority change | The changelog entry’s created |
| Jira work item created or resolved | created or resolutiondate |
| Comment (Jira, Confluence, Loom) | The comment’s created time |
| Confluence page edit | The createdAt of the version that made the change. When a diff spans many versions and the change can’t be pinned to one, show the range (“edited Oct 7 to Oct 21”) |
| Project or goal update, or highlight | Its creationDate |
| Pull request | mergedAt, or createdAt for a new one |
| Meeting | Its start time |
| Loom recording | Its creation time |
| Third-party search result | lastModified, which is the last edit, so it can say “updated” but never “new” |
updated and a page’s last-modified date are not events. A bot, a resync or a later edit moves them. Use them only to pick candidates, then read the history for the event.listConfluenceContentVersions), never from getConfluenceContent metadata: on a live doc, version.createdAt came back as the time of the read.lastModified: null) aren’t windowed. Judge them by their own record, and never present them as new.These gaps showed up on real data. Work around them as described, and say in the footer when one affected the result.
atlassian_user_owns_atlassian_project means the user owns the project, from either end. When they’re the same type, the reading depends on the relationship:
jira_work_item_blocks_jira_work_item: the target blocks the queried item (upstream).jira_work_item_is_blocked_by_jira_work_item: the target is blocked by the queried item (downstream).atlassian_project_depends_on_atlassian_project: the queried project depends on the target (upstream). This one reads the other way round.For any other same-type name, check it from both ends before trusting it. The graph also indexes only Jira’s standard Blocks link type: a site’s own blocker link type (one named “Blocker”, say) doesn’t appear at all. So use the graph’s Jira edges as candidates and a cross-check, and confirm every Jira dependency with getJiraIssue (view: evidence): an inwardIssue on a Blocks link blocks this issue (upstream), and an outwardIssue is blocked by it (downstream). For many items at once, JQL with fields: ["summary", "status", "issuelinks"] returns the same inwardIssue and outwardIssue entries in one call. On a large site, view: evidence returns every custom field (about 25,000 characters per issue), so pass an explicit fields list when you only need links.
atlassian_project_depends_on_atlassian_project shows only on the depending project, and some project links are missing from the graph entirely. For project-to-project edges, use getProject with include: ["dependencies"] and limits: {dependencies: 20}. It returns linkType relative to the queried project: DEPENDS_ON (it waits on the other), DEPENDED_BY (the other waits on it) or RELATED (no direction).getProject with include: ["links"] and linkType: WORK_TRACKING, from Jira work that tracks it, and from Jira keys and URLs in its update notes.listJiraIssueRemoteIssueLinks, since a getGraphContext summary gives only their count.updateType: USER (one cancelled a live project as abandoned), so updateType: USER doesn’t mean a person wrote it, and latestUserUpdate can be a bot’s. Read the creator and the text (an automation account named like …-bot, wording such as “deemed abandoned”) before attributing a status change to someone. Treat such an update as a system update when finding the last update a person wrote, and say so. Bots also appear among followers.ATLAS-123) don’t resolve in getGraphContext. Pass the home.atlassian.com URL or the ARI, which you get from getProject or getGoal. Jira keys do resolve.getWorkActivity windows on when the invite last changed. So Teamwork Graph can’t list a day’s or a week’s meetings. On real data, all 602 events from a 60-day window included only one of the next day’s meetings. Events also carry only attendee and creator edges, with no links to notes, recordings or other occurrences, and the calendar connector’s event URLs don’t resolve in the graph. Take meetings, attendees, responses and earlier instances from the calendar’s own connector (see “Vendor connectors”), and find notes and recordings by search.search nor getWorkActivity can list what arrived in a window: search ranks by relevance, and activity windows on relationship changes. For “since yesterday” in chat or email, run the graph search and keep results whose lastModified is inside the window. Add the vendor connector only when that isn’t enough.getWorkActivity, product reads such as Loom comments, and search. Don’t claim to cover notifications.ExternalOrganisation doesn’t resolve by name. Use it only with an ARI that came back from a result or an edge.getGraphContext with JiraSprint returns “Node type for ATI ‘ati:cloud:jira-software:sprint’ not found”, and a sprint ID doesn’t resolve. Read sprints from Jira (getJiraBoardSprintData), and the work in them from JQL (sprint = <id>). JQL history searches don’t support the sprint field, so when an item joined or left a sprint comes only from listJiraIssueChangelogs.namespace set to the organisation’s own workspaces (the non-fork one beside a forks organisation). Never conclude “not in the code” before that retry.getCodeFile returns a file as one string with no line numbers, and counting by eye drifts. Cite a chunk’s lineRange or a lexical result’s matchedLineNumbers, and run a lexical search with the file’s path to pin other lines. Never retype a file to number it./src/master/) or the repository root. Use getCodeFile’s externalUrl, which is pinned to the commit.external_repository_has_external_pull_request and others), but no edge to an Atlassian project, team or owner, and a Bitbucket repository URL doesn’t resolve. So walk from a repository only to its pull requests, never to find who owns it or what it’s for. Read its owner from files in the repo instead (a compass.yml ownerId team ARI, resolved with getTeam, a manifest’s team field, or CODEOWNERS), and say it was declared there.key >= PROJ-120 AND key <= PROJ-148). A key quoted in a doc may belong to another site, where the same key can be a different issue. Resolve those only from a URL that includes the host, passing the site URL as cloudId. If access isn’t granted, list the item in the footer as unreadable, and don’t count that work as checked.Every skill starts from one object, or a small set of the same kind. Work out what the user gave you, resolve it, and confirm it’s the right one before going further.
| The user gives you | objectType |
Resolve with |
|---|---|---|
| A meeting or calendar invite | ExternalCalendarEvent (LoomMeeting, LoomMeetingRecurrence for Loom) |
The calendar’s own connector (see “Calendars”). In the graph, getWorkActivity with types: calendar and activity: all |
| A Jira work item, release or project | JiraWorkItem, JiraVersion, JiraSpace |
The key or URL |
| A Jira sprint | None in the graph (see “Sprints”) | getJiraBoardSprintData with the board and the sprint’s name or ID |
| An Atlassian project or goal | AtlassianProject, AtlassianGoal |
getProject or getGoal, then the returned ARI or URL |
| A focus area | FocusFocusArea |
getFocusArea |
| A Confluence page, whiteboard or database | ConfluencePage, ConfluenceWhiteboard, ConfluenceDatabase |
The URL |
| A person or team | AtlassianUser, AtlassianTeam |
getPeopleInfo, searchTeams |
| A service or component | CompassComponent, ExternalService |
The URL or ARI |
| A pull request, repo, deployment or design | ExternalPullRequest, ExternalRepository, ExternalDeployment, ExternalDesign |
The URL. A repository links only to its pull requests, commits and branches (see “Code and repositories”), so start from its code with code search to find what it does or who owns it |
| A Slack or Teams thread | ExternalConversation |
The URL (may not resolve; see “Hydrate”) |
| A Google Drive, SharePoint or Dropbox doc | ExternalDocument |
The URL |
| A customer account | ExternalOrganisation |
An ARI from a result only |
| A CMDB object | AssetsObject |
The key or URL |
| A Loom video | LoomVideo |
The share URL |
search (STANDARD), compare the plausible candidates by scope, recency and how central they are, and pick one. If two are equally plausible, ask. Don’t merge two same-named things.getWorkActivity with scope: me.getGraphContext on the anchor with detailLevel: summary, then full only for the relationship types the artifact needs. For anything about change (“since last time”, “while I was away”), pass timeRange.Much of the useful context, such as a decision in Slack or a customer complaint in Zendesk, was never linked to anything. After expanding, run 2 to 4 searches as “Searching” describes. Keep a hit only if it’s clearly about the anchor (same names, keys, people or dates), and mark it as found by search.
getGraphObject call. Use the product tool where the table above names one.raw, “excluded”, missing from the response, or a URL that doesn’t resolve), read it with the vendor’s connector if the client has one. Otherwise the search snippet is the citable text. Quote only words inside the snippet, trim at its ellipses, and don’t retry. Note in the footer that full threads, replies or attachments weren’t read.getPeopleInfo for names, roles and managers. getWorkActivity for what people did recently. getCollaborators and getWorkPortfolio for who works on what.Skills get better with more of the customer’s tools connected, so be explicit about coverage.
Don’t assume a site has every Atlassian app. Check before gathering:
products list that getAccessibleAtlassianResources returns for the site (jira, confluence, goals, projects, loom, bitbucket, assets, focus, teams, artifacts and so on). It lists the apps the user can use there, each with an access level. discover leaves out the operations for an app that isn’t in the list.jira, though some sites list Jira Service Management as its own jsm entry. Only if a skill needs one, check with a single JQL call, projectType = service_desk or projectType = product_discovery, with maxResults: 1 and fields: ["project"]. No results means the user has no projects of that type. On a large site that check can time out: then take the type from projectTypeKey in listJiraProjects results instead.atlassian-design. ADS has no third-party logos, so use the object-type icon (comment for a chat message, hashtag for a channel, page for a doc, pull-request for a PR, calendar for an event, globe for anything else).products list, as muted tags labelled “Not available on this site”addGraphContext to connect work to projects and goals, and remote links to point Jira at third-party sources, instead of copying content across.getPeopleInfo or lookupJiraAccountId. Never guess an account ID.Follow the calling skill’s delivery mode. A skill that explicitly selects “Answer-first delivery” uses the flow below. Other skills keep their existing artifact flow: build the static artifact unless a live one is available and the skill’s “When live” section says what it adds. Load atlassian-design only when building a report or artifact.
products list from getAccessibleAtlassianResources; do not choose another site silently. If artifacts is absent, skip publication tools and offers. If it is present, confirm that createArtifactsUpload and publishArtifact are available in this session, through discover if necessary, without creating an upload as a test. If availability cannot be confirmed, say so when relevant and hand over the report file.Don’t publish by default. Publishing is a write, so hand over the file and offer to publish a private, read-only copy as an Atlassian Artifact. Publish only when the user says yes, or has already asked for it in this request.
localStorage, sessionStorage or IndexedDB, which the artifact viewer may block. Inline only the icons you use, and don’t embed raw tool output, so the file stays small.createConfluenceContent.When the user agrees:
wc -c < file.html. Checksum, as base64 SHA-256, not hex: openssl dgst -sha256 -binary file.html | openssl base64 -A.createArtifactsUpload (through discover and executeWrite) with length and checksum, then send the exact bytes to the pre-signed URL as its instructions say.publishArtifact with the contentId from step 4, a name, contentType: text/html, and a description that summarises what the artifact actually contains (up to 1000 characters, used for search). To update an artifact you published earlier, pass its id. Each publish is a new version that can’t be changed.publishArtifact returns a link that grants nobody access. Offer to share it with the people it’s for (attendees, a leader, a team) and, if the user agrees, call shareArtifact with ari:cloud:identity::user/<accountId> or team ARIs. It only grants view access to named people, never to everyone with the link.If the client can’t upload over HTTP, hand over the HTML file and say why it wasn’t published.
A static artifact can’t call tools, so it shows what was true when it was built. To keep one fresh, run the skill again and publish with the same id, for example from a scheduled task the user set up to publish. Actions are links, or buttons that copy a command such as /meeting-prep [title].
A live artifact runs inside a host that explicitly supports tool calls from page code. Having an MCP connection in the agent conversation is not enough. Build one only when the host’s documented runtime and permissions are available, the skill has a “When live” section, and the user requests it or that skill explicitly makes it the default. A skill using answer-first delivery still requires a report or live-export request first.
Read live-artifacts.md before building one, then load only the adapter for the actual host. Use the host’s current documentation when it differs from an included adapter. Do not rename one host’s APIs, capability declarations, connector identifiers or error codes to make them look universal. If the host or its capabilities cannot be confirmed, retain the conversational answer or requested static report and explain why live refresh is unavailable.
A live artifact belongs to its host. Publishing an HTML snapshot to Atlassian Artifacts is a separate, static export, offered only when that service is available and the user requests publication.
When the user asks for a mockup, or gives sample data:
# for every link unless told otherwise.A skill that loads this file should state:
objectType it resolves to, and how to resolve it.atlassian-design.