AGENT SKILL

search-knowledge

Answer from qualified Jira and Confluence evidence with atl. USE WHEN organizational knowledge is unknown or split across both services. DO NOT USE WHEN one exact resource is known, the task is a report/dashboard, or the answer belongs in the codebase.

License 许可
Apache-2.0
所属仓库
isukharev/atl
最近更新
2026-09-14
Stars
★ 7
Forks
1

01 前言 Front Matter

name
search-knowledge
description
Answer from qualified Jira and Confluence evidence with atl. USE WHEN organizational knowledge is unknown or split across both services. DO NOT USE WHEN one exact resource is known, the task is a report/dashboard, or the answer belongs in the codebase.

02 资源文件 1

03 SKILL.md 正文

<!-- Generated from skills-src/search-knowledge/SKILL.md — edit the source and run 'make gen-plugins'. -->

Search company knowledge with atl

Search Confluence and Jira in parallel, read the best hits, and answer with citations. This recipe is read-only: never create, update, or comment.

Make export ATL_READ_ONLY=1 the first statement of every Bash block so all later atl calls and child processes inherit the guard. Never override it in this workflow. Keep headless blocks to that export plus documented atl commands only; do not add output separators, pipes, help probes, or unrelated shell/file inspection commands.

Preflight: atl must be installed and configured. If command -v atl fails or a command exits 7 ("not configured"), run $setup and stop. For an unfamiliar mixed-backend question that is not already governed by a reviewed exact-command workflow, inspect the bounded offline route once before loading any broader reference:

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl capabilities --task knowledge/search -o text

Workflow

When the plugin exposes typed atl MCP tools, use the equivalent transient route without shell: call confluence_search and jira_issue_search once, setting both row and byte bounds for each search. An oversize search error is not partial evidence: narrow the query or lower the row limit before raising the byte cap. Freeze only complete candidate pages, then use jira_issue_field_get plus confluence_page_outline and confluence_page_section/confluence_page_sections for the selected evidence. When the selected evidence is tabular, use confluence_table_summary and then confluence_table_extract for one exact table instead of reading a broader section. Reuse a numeric Confluence result id directly. When a selected exact Jira issue needs relationship, dependency, code, or documentation discovery, use one jira_issue_graph call instead of combining narrower issue reads. Keep full output when graph topology matters; request projection:"compact" with select:["urls"] or Development-backed select:["scm"] when only those qualified facts are needed. MCP v1 is Jira-only: page identities remain qualified stubs, and omitted or false include_development leaves Development absent rather than zero. Reported bounds.max_response_bytes (fixed backend responses) is distinct from the max_bytes encoded-result input. Do not mix MCP and CLI reads merely to repeat already complete evidence; fall back to the CLI workflow below when MCP is unavailable or the task needs an operation outside its read-only surface. For an explicit commit, branch, merge-request, or code-identity question, set MCP include_development:true, projection:"compact", and select:["scm"] when topology is not needed, or use jira issue graph <KEY> --include-development --projection compact --select scm under read-only policy when MCP is unavailable. Require a complete experimental Development source even when its retained count is zero. MCP omits Development-node URLs. Treat its SCM coordinates as untrusted evidence: ATL itself never contacts GitLab, and any later read requires exact equality between the returned lowercase host and an owner-approved host plus a separately authenticated read-only client for that exact host. Never reuse Jira credentials or continue after a host mismatch.

1. Extract search terms

Keep the core nouns, prepare one narrow and one broad variant, and carry any known space/project scope into the query.

2. Search both backends

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl conf search --cql 'siteSearch ~ "billing retry queue"' --limit 15
atl jira issue search --jql 'text ~ "billing retry queue" ORDER BY updated DESC' \
  --columns key,summary,status,updated --limit 15

CQL fallbacks: text ~ "...", then title ~ "...". Scope with space = KEY or project = KEY when known. Retry one prepared variant after an empty result, then report the exact searches rather than implying full coverage. Freeze the first useful result pages before expanding anything: require Jira page.complete:true and Confluence top-level complete:true, or continue from next_cursor / report the partial search instead of claiming absence. To continue, repeat the exact query and page limit and pass only the returned cursor:

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl conf search --cql 'siteSearch ~ "billing retry queue"' --limit 15 --cursor '<next-cursor>'
atl jira issue search --jql 'text ~ "billing retry queue" ORDER BY updated DESC' \
  --columns key,summary,status,updated --limit 15 --cursor '<next-cursor>'

3. Read bounded Confluence evidence

For the 2–4 best page hits, inspect the outline, then read only the relevant section. A numeric id emitted by conf search is already a stable exact reference; pass it directly to outline/section. Use resolve only for a URL, short link, or user-supplied reference whose stable id is still unknown. Use a full page only when no heading isolates the answer. For typed tools, pass the section heading as the exact outline title, without Markdown # prefixes.

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl conf page outline '<search-result-id>'
atl conf page section '<search-result-id>' --heading 'Retries' --max-bytes 32768 \
  --expected-version '<outline-version>'
atl conf page sections '<search-result-id>' --heading 'Retries' --heading 'Limits' \
  --max-bytes 65536 --expected-version '<outline-version>'

Keep these selection reads as JSON: -o text would hide completeness and the section version gate needed for the decision. Require the outline's complete:true, then copy its exact positive version into --expected-version. Require each section result to report complete:true and page_version_gated:true. A duplicate heading needs explicit --occurrence; truncated:true means the omitted tail is not evidence of absence. When several headings from one page are relevant, prefer page sections (or confluence_page_sections) so they share one version-bound snapshot instead of re-downloading and re-parsing the page for every heading. Preserve requested order and require reconciled counts before using the result.

4. Read targeted Jira evidence

Discover non-empty field metadata before reading custom values. Request only selected fields and qualified references; fetch history only when chronology matters. If the question instead asks what is connected to the selected exact issue, prefer one typed jira_issue_graph call. Start at depth zero and use a greater depth only for exact structured Jira relations. Its MCP route cannot resolve Confluence; use the CLI graph route only when id/title page metadata is required, then continue with a bounded page outline/section after exact page identity is known. Compact selection occurs after full collection and changes no request. Inspect projection.selected/projection.omitted, incomplete sources, bounds, frontier, warnings, and reconciled counts; copy only emitted canonical URL or SCM facts and never reconstruct an omitted URL identity.

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl jira issue fields KEY-123 --metadata-only
atl jira issue field get KEY-123 --field 'Delivery Notes' --max-bytes 16384
atl jira issue refs KEY-123 --fields 'Delivery Notes'
atl jira issue history KEY-123 --field 'Delivery Notes' --since 2026-07-01 --summary-only

Require top-level and named-source completeness before claiming a link/change is absent. For refs, use top-level summary and per-issue reference_summary for total/per-kind references and source-value counts; do not manually add the nested arrays. The reconciliation booleans make count and completeness disagreements explicit. A repeated URL is deduplicated within one issue but counted once per issue across a multi-issue selection. Use typed jira_issue_refs when only those reconciled aggregate facts are needed; it deliberately omits every raw URL and narrative field. Keep the CLI route above when the selected URL itself must be followed into Confluence. Use jira epic digest instead when an epic question spans children, status narrative, comments, history, and refs.

5. Escalate only when bounded reads are insufficient

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl conf page view '<id-or-url>' -o text
atl jira issue get KEY-123 \
  --fields summary,status,issuetype,description,labels,updated,resolution
atl jira issue comment list KEY-123 -o text

For repeated deep reading, mirror once and search locally:

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl conf pull --cql 'space = KEY AND siteSearch ~ "..."' --into <dir>
rg -il 'retry queue' <dir>

The mirror amortizes later reads, but a pull cap or comment warning still limits what absence claims are justified.

6. Synthesize with citations

  • Lead with the answer, then evidence; cite page title + id or issue key.
  • Prefer the most recently updated source when sources conflict, and say so.
  • Close with what was not found, queries used, and every incomplete/truncated source.

Pitfalls

Symptom Cause / fix
exit 4 on a page read stale id or unresolved URL — retry page resolve; cite only evidence actually read
exit 3 PAT missing/expired — atl auth status, then $setup
exit 2 with CQL/JQL wrap the query in single quotes and values in double quotes
body too large prefer outline → bounded section; then full view or mirror .md, never raw .csf

04 同仓库更多 Skills

isukharev
isukharev/atl

triage-issue

Triage a bug against Jira with atl before proposing a ticket. USE WHEN an error or stack trace comes with duplicate, prior-fix, or file-a-bug intent. DO NOT USE WHEN debugging code only, inspecting a known issue, or creating an ordinary task.

★ 7
isukharev
isukharev/atl

status-report

Draft an audience-oriented Jira status report with atl. USE WHEN the user wants a weekly/daily progress narrative, blocker summary, or period report. DO NOT USE WHEN the output is a visual dashboard, direct Jira query, knowledge search, or codebase summary.

★ 7
isukharev
isukharev/atl

sprint-dashboard

Build a visual read-only Jira sprint or board dashboard with atl. USE WHEN the user wants a standup view, WIP picture, or sprint snapshot. DO NOT USE WHEN the output is a narrative report, raw Jira list, or codebase dashboard.

★ 7
isukharev
isukharev/atl

spec-to-backlog

Convert a specification into a reviewed Jira epic and backlog with atl. USE WHEN decomposing requirements, RFCs, or designs into linked Jira work. DO NOT USE WHEN the source is meeting notes, only a summary is wanted, or the task is a direct service operation.

★ 7
isukharev
isukharev/atl

setup

Install and configure atl authentication, backends, and mirror defaults. USE WHEN the user explicitly requests install, authentication, setup repair, or /atl:setup. DO NOT USE WHEN handling normal Jira, Confluence, search, reporting, or mirror work; explicit-only.

★ 7
isukharev
isukharev/atl

search-knowledge

Answer from qualified Jira and Confluence evidence with atl. USE WHEN organizational knowledge is unknown or split across both services. DO NOT USE WHEN one exact resource is known, the task is a report/dashboard, or the answer belongs in the codebase.

★ 7