Answer a question in the conversation about how the product behaves (“Which people does the user picker suggest first?”, “What happens to a trial site’s data when the trial ends?”) for someone who doesn’t read code: a support engineer working a ticket, a customer success manager, a product manager or a docs writer. In a few minutes they get a plain answer, the behaviour step by step, what can change it, whether the docs are right, and who to ask if they need more.
Today that question goes into an engineering channel and waits. The docs may be out of date, and the person who knows may be busy. The value of this skill is the judgement a code search results page can’t make. It reads the code that decides the behaviour and explains it in the product’s words. It keeps what the code shows apart from what it can’t show: a service whose code isn’t indexed, whether a feature flag is on, a customer’s own settings. And it checks the docs and chat against the code, so a wrong answer that keeps getting repeated gets caught.
Load the teamwork-graph-context skill first and follow it for gathering context, labelling sources, keeping sensitive content out and optional publishing. This file adds what’s specific to explaining behaviour from code.
This skill selects “Answer-first delivery” in teamwork-graph-context: gather and assess, answer in the conversation, then ask whether the user wants an HTML report. Do not write report data, run a renderer or create an artifact unless the user requests an export, HTML report or publication. Use the existing report layout only for that optional export. Offer Atlassian Artifacts publication only after confirming availability; exporting does not authorise publishing.
These rules add to “Sensitive content” in teamwork-graph-context, and apply to the artifact, excerpts, your reply and any log.
code-search is in the site’s products list (see “Atlassian apps on the site” in teamwork-graph-context). If it isn’t, say so before building: this skill can’t answer without code. Offer /whos-the-expert to find who to ask instead.teamwork-graph-context describes: GitHub, to read a pull request’s body when the graph returns it empty (raw: {}). Slack, to read an answer in a thread when only the question shows in the snippet.Unless the user asks for a deeper pass, stay within these, and say in the footer if one was reached:
| Tool | Cap | Where |
|---|---|---|
searchCode |
9 | Up to 3 in Step 2: 2 initial searches and 1 reserved retry or follow-up. Up to 3 in Step 3 to follow an identifier, and up to 3 in Step 3 to pin line numbers |
getCodeFile |
8 files | Step 3, including a manifest and a changelog |
scanCodeRepo |
1 | Step 3, the home directory |
search |
4 | 3 in Step 5, 1 in Step 6 for the Compass component |
| Product reads | 5 objects | The ticket in Step 1, up to 3 docs in Step 5 (getConfluenceContent or getGraphObject, each doc counts), 1 pull request list in Step 4 |
getGraphContext |
1 | Step 6, the Compass component |
getTeam or searchTeams |
1 | Step 6 |
searchCode, getCodeFile and scanCodeRepo are reached through discover and run with executeRead. search, getGraphContext and searchTeams can use Rovo credits. A typical run makes 20 to 30 calls. Send calls that don’t depend on each other together, as “Fetch in parallel” in teamwork-graph-context describes: the code searches in Step 2, the file reads in Step 3, and the sweep in Step 5 alongside Step 3.
getAccessibleAtlassianResources once for the cloudId and the site’s products list, and check for code-search.getJiraIssue (default view), and take the question from its summary and description. If they gave a Slack or Teams thread, take the question from what they pasted or from the search snippet. Keep the exact text of any error message or label the customer saw. Drop customer names, IDs and links as “Sensitive content in code” says.Send at most 2 initial searchCode calls together, each with maxResults: 10, and reserve the third Step 2 slot until their results have been filtered:
mode: hybrid with the behaviour in plain words (“which users the user picker suggests first”).mode: lexical with the most distinctive user-visible string, if there is one (“No matches found”); otherwise mode: hybrid with the feature plus the mechanism in code words (“user picker suggestions sort”).If the user named a repository, organisation or workspace, pass it as repo or namespace on every call.
Drop noise before anything else. On real data, unfiltered searches return mostly copies of open-source code and files that aren’t code. Drop a result when:
fork), or the repository is a copy of a well-known open-source project (tomcat, hibernate, moby), unless the question is about that projectvendor/, node_modules/, third_party/, dist/, build/, *.min.js, lockfiles, *.generated.*CHANGES or release logs (Step 4 reads changelogs for history, not behaviour), licence filestest-data/, fixtures/, __fixtures__/, recorded API responsesKeep tests (*.test.*, *.spec.*, __tests__/): their names often state the rule in plain words. Keep examples and docs inside the repository too, but as supporting, not as the behaviour itself. Count what you dropped for the footer, by reason (“18 results from forks and vendored code, and 6 from other products, left out”).
If more than half the first round was noise, or nothing was kept, use the reserved third slot for one searchCode with mode: hybrid, the behaviour in code words, and namespace set to the kept workspaces, joined with |. If nothing was kept, set namespace to the organisation’s own workspaces seen in any result instead: the non-fork workspace beside a forks one (acme beside acme-forks), or any workspace that isn’t a fork. If the kept results cluster in one repository of a large shared workspace, add that repository as repo too. Run this retry before “Nothing kept” below; Step 2 still makes at most 3 calls. When no retry is needed, the reserved slot may instead fund the feature-and-mechanism search if it wasn’t already run and could change the choice of home. Otherwise leave it unused.
The same file can come back at two commits. Read it once, at the commit most other kept results from that repository carry, and say in the footer that another version was indexed.
Pick the home: the repository and directory where most kept results cluster, usually one package or service (“packages/session in beacon-web”). Prefer the package that decides the outcome over one that only displays it: a component that fetches and filters suggestions, not the one that draws the list. If kept results split between two products with the same words, use the product the user named, or ask. Don’t merge them.
Only shared code found: if the product the user named has no code in the results, but a shared component it may use does (a design-system or platform package), use the shared component as the home. Say in the short answer’s first sentence that this is the shared component, and that how the product sets it up isn’t in the code we can search. The verdict can be no better than “Partly answered”. If a doc or record suggests the product doesn’t use the component everywhere (some fields call the service another way), say so in the short answer: “This may not apply to every [product] field.”
Nothing kept after the retry: the verdict is “Not in the code we can search” (Step 7). Skip Steps 3 and 4, and still run Steps 5 and 6, so the user gets the docs and an owner. Don’t widen the search to generic words to find something.
scanCodeRepo call: workspace and repo from the result, commitHash from its version, root set to the home directory, limit: 200. This shows the manifest (package.json, pom.xml, catalog-info.yaml, compass.yml, CODEOWNERS), any CHANGELOG.md, and how the code is laid out.getCodeFile, together where you can, passing each result’s workspace, repo, path and version (as commitHash). In this order:
Take line numbers from code search, not by counting. getCodeFile returns the file as one string with no line numbers, and counting by eye drifts. searchCode results carry each chunk’s lineRange, and lexical results add matchedLineNumbers. Cite those. Counting a few lines inside a returned chunk, from its lineRange start, is fine: chunks are short. Counting from the top of a whole file isn’t. To cite lines no search has returned, run a lexical searchCode for a distinctive line in that code (an identifier or a string on it) with the file’s path, up to 3 of these. If the client can save a tool result straight to a file, numbering that file (nl -ba) works too. Never retype a file to number it. If a range can’t be pinned this way, cite the function by name with no line numbers.
searchCode with mode: lexical, the identifier as the query, and the home’s namespace. Up to 3 of these, apart from the pinning searches. Spend them on the hand-offs that decide the outcome first. For a service known only by its URL or endpoint, run one mode: hybrid search with the service’s name and the endpoint path. If it returns only callers, stop: more searches won’t find the service. If none finds where it’s defined, the step is a hand-off (below).sortByRecent)”)| Kind | Use it when |
|---|---|
| Shown in code | The cited lines do this whenever the step is reached |
| Depends on a setting | A feature flag, experiment, config value, permission, plan or edition check decides what happens, or an option the product using a shared component passes in |
| Hand-off | The code passes the decision to something whose code you didn’t read: a service call, an API, a library you couldn’t find |
| Default or limit | A fixed value shapes the result: a timeout, a maximum, a page size, a default choice |
The page doesn’t show the kind. It decides what the reply, the checklist and the settings table can use, so the sentence says it in words: the setting by name, the number with its unit, and the service a hand-off goes to.
idleTimer.ts, “Suggestion order” for sortByRecent.ts), not its code name. A file that several steps cite keeps one name.Code search has no history for a file, so use what the repository records. One of these, the first that applies:
listBitbucketRepoPullRequests (through discover) with workspaceId, repoId, state: MERGED, a q filter on the title (title ~ "<hook>") and pagelen: 10. Keep pull requests whose title is about the behaviour.If none applies, show “Not checked: no change history for this code” in the footer. Never date a change from a commit hash alone.
Run these together with Step 3, each search with mode: STANDARD and limit: 20:
targetApp: CONFLUENCE, with the behaviour in the user’s wordstargetApp: THIRD_PARTY, with the same, for Slack, GitHub, Google Drive and public docstargetApp: JIRA, with the user-visible string or the feature plus “bug”, for work items and support tickets about itThen:
teamwork-graph-context says, and drop direct and group messages.getConfluenceContent (content_format: markdown, detail: full), and third-party docs (a public developer site, a Google Doc) with getGraphObject. If one won’t hydrate, its snippet is the citable text, as teamwork-graph-context says.| Finding | When | Lozenge |
|---|---|---|
| Disagrees with the code | It states something a “Shown in code” or “Default or limit” step contradicts: a different number, order, condition or outcome | Disagrees (danger) |
| Matches the code | What it states, the trace shows | Matches (success) |
| Can’t check | It’s about a hand-off, a setting’s live value, or something the trace didn’t reach | Can’t check (default) |
The code wins for what the code does. A doc can still be right about a service whose code wasn’t read, so a claim about a hand-off is “Can’t check”, never “Disagrees”. A plan, proposal or RFC describes what someone meant to build, not how it works: it’s “Can’t check”, noted as “a plan from [Mon YYYY]” using its created date, or “a plan, last edited [Mon YYYY]” when only lastModified is known, never “Disagrees”.
lastModified (“Asked 4 times in Slack in the last 90 days”). One question posted in several channels counts once. If none fall inside the window but some are older, say when it was last asked instead (“Last asked in Slack in Jul 2026, 2 times this year”). Never list who asked, and don’t link the questions: a chat title names the person. A message that answers the question can be linked as a finding, with its author named as teamwork-graph-context allows.Take the owner from the first source that names one, and say which:
"team": "..." in a package.json), a CODEOWNERS entry for the home path, or the owner in catalog-info.yaml or compass.yml.
compass.yml’s ownerId does), read it with one getTeam call (through discover), passing it as teamId. Otherwise use one searchTeams call on the exact declared name. Link it only if a returned name matches exactly, or if the ARI resolved. A team whose name differs but whose description names this component can be shown as “Possible match”, labelled found by search. Otherwise show the declared name as plain text.compass.yml links often have one). A channel for pull request or build notifications isn’t one: show it, if at all, as “Code notifications”. Never name a person from these files as the owner.search (targetApp: ALL) for the repository’s name. If a Compass component’s snippet or links name this repository, read its owner with getGraphContext (objectType: CompassComponent, the component URL, relationshipTypes: ["atlassian_team_owns_compass_component"], detailLevel: full).The graph holds nothing useful for a repository here. A GitHub repository resolves with no relationships, and a Bitbucket repository URL doesn’t resolve. So don’t spend a call on it. If no source names an owner, say “No owner recorded”, and suggest /whos-the-expert with the feature as the topic. Never name a person from commit or pull request activity as the owner.
Each service a hand-off goes to gets its owner for the map in Step 8 too: the team a source above or a doc from Step 5 names for that service, or “No owner recorded”. It matches the service’s row in Who owns it. Don’t spend calls looking for it.
Verdict, one of these. The page doesn’t show it, so the short answer says in plain words anything it leaves open:
Never: claim a flag or setting’s live value, name a cause for one customer’s case, guess what a hand-off does, or call the code a bug.
Docs that disagree: if a finding is “Disagrees with the code” about something the answer says, add one plain sentence to the short answer with the doc’s smart link and what it still says (“The help article [link] still says 60 minutes, which changed to 30 in version 3.0.0.”). The step it contradicts is in What the docs and chat say. Rank disagreements by audience: customer-facing docs first, then support articles and runbooks, then internal pages, then chat. Within each, newest first.
The short answer: 2 to 4 plain sentences, the first answering the question as asked. Every sentence must be backed by a trace step, or for a doc that disagrees, by its finding. Name any setting that changes the answer. For “Partly answered”, the last sentence says where the code we can see stops.
What to check on the account, for a question about one customer: the settings and inputs from “Depends on a setting” steps, as a checklist in plain words (“Is the site on the new user management?”). When only shared code was found, add where it happened (“Which field or screen was it?”), since the product may set the component up differently in each place. Never answer them.
Suggested reply, when the anchor is a ticket or the user says it’s for a customer: 2 to 5 sentences the user could send, labelled “Proposed”. It uses only “Shown in code” and “Default or limit” steps, in customer language. Leave out a default the product or site can change (“up to 100 people” when the product sets its own maximum). If little is left, a short reply that says what’s known and asks the customer for the facts on the checklist is fine. It names no flags, internal services, endpoints, repositories or people, and no “Depends on a setting” step unless it’s a setting the customer controls.
Stop condition: stop gathering when the trace reaches the outcome and the owner is found, or when the budgets for Steps 2 and 3 are spent. One extra getCodeFile is fine if it could change the verdict.
The skill reads by default. It offers one write only when the user gave a Jira or Jira Service Management ticket and the report has actually been published. Without a published report, do not offer the comment or publish a report just to enable it:
addOrEditJiraIssueComment. On an error, say what happened and re-read the ticket’s comments before offering again.Never edit a doc that disagrees with the code. The explainer shows the disagreement, and the user takes it to the doc’s owner.
Ask whether the user wants this exported to an HTML report. If they have already explicitly requested an export, HTML report or publication, proceed with that requested build without asking again. Otherwise stop here until they answer; a normal invocation of this skill does not request a report. Follow the shared availability and confirmation checks before offering or performing publication.
Only after the user requests the report, write its data as one JSON file and run the renderer in this folder:
python3 <this skill's folder>/render.py explainer.json how-it-works-<topic>.html
example.json in this folder (made-up sample data). Copy its keys and fill them from the steps above. Text fields, links, lozenges and icons follow the shared rules in the atlassian-design skill’s references/data-format.md. Leave out a key you have nothing for.question and about head the page, about the “[feature] in [product]” phrase from Step 1, and readFrom is {"repository", "commit", "date"} for the header’s date, the map and the trace (the date you read it, never the commit’s date). askedOn is the ticket’s link with its status, when the anchor was a ticket, shown in Suggested reply. answer is the 2 to 4 sentences, as paragraphs, each a text field, with a doc that disagrees as a link in it. Each of steps is {"text", "code", "test", "excerpt"}: code and test {"path", "lines", "url", "name"} with lines as [first, last] and name the test’s name, and excerpt up to 12 lines as {"n", "code"}, with {"gap": true} between runs that aren’t next to each other, secrets cut. map is {"trigger", "parts", "links", "outside"} for Where it happens: trigger the short phrase from Step 1, parts a {"path", "name"} for every file a step’s code cites, with path exactly as in code and name its plain name from Step 3, links a {"from", "to", "verb", "step"} for each link from Step 3, with from and to paths from parts and step one number, and outside a {"name", "steps", "owner"} for each service a Hand-off step hands to, with steps the numbers of the steps that hand to it and owner from Step 6, left out when none is recorded. settings are {"name", "kind", "changes", "steps", "who"}, with steps the numbers of the steps it touches ([2, 3]), checklist the questions for one customer with checkNote above them, docs the findings as {"link", "claim", "verdict", "meta"}, questions the line counting recent questions, bugs the open bugs as links, changes {"version", "date", "text", "link"} with changesNote, owners {"label", "link" or "text", "from"}, reply the suggested reply, and notAnswered the line for a behaviour set aside. Put code, file names, settings and flags in backticks.references/hand-built.md in this folder.The rules below say what the renderer builds, and what each part of the data must hold.
Sections 2 to 11 are cards, each with its title in plain text and no icon.
/how-it-works skill tag, the question as the page’s only h1, then one line: “[about], as of [the date you read it].” (“Invoice search in Ledger, as of Oct 27, 2026.”). No tool returns when a commit was made, so never call it the commit’s date. The repository, commit and files read go in the sources footer.map and steps, so every run draws it the same way. It shows what calls what, left to right: the trigger, then a node for each file a step’s code cites, inside one frame for the repository in readFrom, titled with the repository and its team, with “Code we read, at [commit]” under it, then a dashed node for each service a Hand-off step hands to, under “Outside the code we can see”, with its owner or “No owner recorded”. A file’s node has its plain name and its file name, the same name its steps’ code chips show, so there are no step numbers on it. The edges are the trigger’s arrow to step 1’s file, a hand-off step’s arrow from its file to its service, and each link in map.links, labelled with its verb. A link is drawn only from what a cited line shows, never from the step order. Settings aren’t in the diagram; What can change this has them. With no link, or no cited file, there’s no card, since the step list already shows the order. A map.parts path no step cites, a cited file with no name in map.parts, a link to a file that isn’t in map.parts or to itself, or a step number that isn’t a step, or that cites neither of a link’s files, stops the renderer with a data error.angle-brackets icon and the file name (“UserPicker.tsx”), linking the file at the cited lines, using the externalUrl from getCodeFile with a line anchor where the host supports one. The lines and the commit are in the chip’s tooltip, and the commit is in the sources footer too. Under it, a collapsed “Show the code” disclosure with up to 12 lines from the cited range, in monospace, with their line numbers and secrets cut. If the lines that matter aren’t next to each other, show each run with its numbers and an ellipsis row between them. Supporting tests appear as a second chip with the test file’s name, and the test’s name in its tooltip. Then the traceNote line in small subtlest text.checkNote line in small subtlest text, then the checklist as checkboxes. Ticks aren’t saved.teamwork-graph-context’s labelling rule: no chip is marked as found by search. Say once in the footer that the docs and chat were found by search. Then the count of recent questions, if any, as one line of small text, and open bugs as rows with a smart link and its status lozenge.changesNote line in small subtlest text./whos-the-expert as the next step.teamwork-graph-context describes, plus: the repositories and commits read, the number of files read and searches run, how many results were left out, by reason, where the trace stopped and why, any other indexed version of a file, any cap reached, and “Not checked: no change history for this code” if Step 4 found none.Static only. The answer depends on reading and judging code, and on the sensitive-content rules, which page code can’t apply. The explainer is pinned to the commit it read. To refresh it after the code changes, run the skill again.
teamwork-graph-context, offer a private, read-only copy named “How it works: [the question, shortened]”. Publish only if requested; report export alone does not authorise it.