From aria-knowledge
Mirrors approved decisions from the knowledge folder to connected Notion, Confluence, or Google Docs via ~~docs MCP. Designed for external syncing of decision records, ADRs, and wiki exports.
How this skill is triggered — by the user, by Claude, or both
Slash command
/aria-knowledge:sync-decisions [<decision-slug>|--all|--since YYYY-MM-DD] [--target <space-or-page>][<decision-slug>|--all|--since YYYY-MM-DD] [--target <space-or-page>]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Read approved decisions from `{knowledge_folder}/decisions/` and write them out to a connected `~~docs` MCP destination (a Notion page, Confluence space, Google Doc, etc.). The only v2.18.0 skill that writes externally; embeds Rule 22 advisory preamble per [ADR-016](https://github.com/mikeprasad/knowledge/blob/main/projects/aria-cowork/decisions/016-rule-22-advisory-preamble-for-external-writes...
Read approved decisions from {knowledge_folder}/decisions/ and write them out to a connected ~~docs MCP destination (a Notion page, Confluence space, Google Doc, etc.). The only v2.18.0 skill that writes externally; embeds Rule 22 advisory preamble per ADR-016.
Canonical resolution: This is the Claude Code variant. When both plugin-claude-code and plugin-claude-cowork are loaded in the same session (most common in Claude Desktop), bare /sync-decisions resolves to this skill — aria-knowledge (Code) is the canonical owner of all 24 dual-port skills per ADR-094 §Part 1. The Cowork variant is namespaced-only: /aria-cowork:sync-decisions.
Before Step 0: Check that the Bash tool is available in this session. If Bash is NOT available (you are running in Claude Cowork or another non-Code runtime), surface the following notification and wait for explicit user confirmation:
⚠️ Runtime mismatch — you invoked aria-knowledge's
/sync-decisionsfrom a non-Code runtime.This skill requires connected ~~docs WRITE MCPs (Notion, Confluence, Google Docs), which are typically only present in Cowork. The Cowork-native variant has working MCP write access. Use
/aria-cowork:sync-decisions.Use
/aria-cowork:sync-decisionsinstead? (y/n)
Wait for an explicit reply:
y / yes — Use the Skill tool to invoke aria-cowork:sync-decisions with the same arguments the user provided to this invocation. Do not proceed with this skill's steps; the cowork variant takes over and runs to completion. This is the default-yes path — auto-redirect is the helpful action.n / no — Proceed with this (aria-knowledge) variant anyway despite the runtime mismatch. The user has explicitly opted in.This gate applies even when mode = auto per ADR-094 §Part 3. Auto mode's "implicit-yes on all gates" rule is suspended for the runtime-mismatch check — auto trusts that the user invoked the correct variant, and this gate enforces that precondition. All other auto-mode gates remain bypassed. The friction cost is now low: on y, the auto-redirect runs the correct variant with the original args.
If Bash is available, proceed to Step 0.
Read ~/.claude/aria-knowledge.local.md and extract knowledge_folder. If the file doesn't exist, stop: "aria-knowledge is not configured. Run /setup to get started."
Verify {knowledge_folder}/decisions/ exists. If not, stop: "No decisions/ folder found. Nothing to sync."
Lazily create {knowledge_folder}/logs/sync-decisions.md if it doesn't exist (used by Step 7 for sync history).
Check Claude's available tool list for ~~docs MCPs that support WRITE operations:
~~docs (notion, atlassian, box, egnyte, google docs): if connected, check the MCP's exposed tools — ~~docs MCPs that only expose read_page / search_pages are READ-ONLY for this skill's purpose. Need a write surface (create_page, update_page, append_block_children, or equivalent).If NO ~~docs MCP with write capability is connected, output the standard fallback notice and stop:
No required MCPs connected for
/sync-decisions. This skill writes externally — needs a~~docsMCP with write capability (page creation or block append). Connect Notion, Atlassian (Confluence), Box, Egnyte, or Google Docs via Claude Code's MCP config (or Cowork Settings → Connectors). See CONNECTORS.md. Skipping this run.
Per ADR-015.
Determine which decisions are candidates based on args:
| Arg | Candidates |
|---|---|
| (none) | All decisions whose synced_to_~~docs: frontmatter field is absent OR older than file's last-modified time |
<decision-slug> | Just the named decision (e.g., /sync-decisions 069-karpathy-4-line-foundation) |
--all | Every decision in decisions/, regardless of prior sync state |
--since YYYY-MM-DD | Decisions modified or created on/after that date |
Read each candidate decision file from {knowledge_folder}/decisions/. Cache them in working memory.
If zero candidates: report "No decisions need syncing" and stop.
Determine the destination on the ~~docs MCP side. Args + heuristics:
| Source of target | Used when |
|---|---|
--target <space-or-page-url> from args | User specified |
sync_target: frontmatter field on the decision | Decision specifies own target |
default_sync_target from aria-knowledge.local.md (if set) | User has a global default |
| Ask user interactively | None of above resolved |
If target resolution requires asking the user, present:
Which destination?
- (a) Existing page URL: paste the ~~docs page URL where decisions should be appended
- (b) New top-level page: I'll create `aria-knowledge-decisions` (or a name you provide) in the workspace root
- (c) Cancel this sync run
Decision-specific syncs (where decisions/<slug>.md has its own `sync_target:` field) override this; this prompt only fires for decisions without a per-file target.
If no target resolvable + no interactive answer, abort with clear message: "No sync target resolvable. Set default_sync_target in aria-knowledge.local.md or invoke with --target <url>."
For EACH candidate decision, walk through this checklist:
Before each external write — Rule 22 advisory checklist
This skill writes to an external system. aria-knowledge's PreToolUse hook gates Edit/Write but does NOT catch MCP write tools — Rule 22 here is text-only discipline per ADR-016.
1. **State the change in one sentence.** "Writing decision <slug> to <target-url-or-page-title>."
2. **Why this destination?** Is this the right audience for this decision content? Could it leak into a view the user didn't intend (public workspace, wrong project, wrong channel)?
3. **Reversibility check.** Can the user edit/delete the write from <vendor> after it lands? (For Notion / Confluence / Google Docs: YES, user can edit at destination. For Box / Egnyte: depends on workspace permissions. Note any constraint explicitly.)
4. **Surface for explicit go.** Present the full proposed write content + destination. Wait for explicit user `yes` / `go` before calling the write tool.
Concretely: for each decision, surface this block to the user:
Decision: <slug>
Source file: decisions/<slug>.md
Destination: <target-url-or-page-title> on <vendor>
Operation: <create new page | append to existing page | update existing page>
Reversibility: <user can edit at destination: yes/no/constrained>
--- Proposed write content (preview) ---
<the full decision content as it will appear externally — markdown if Notion/Confluence; plaintext if Google Doc; etc.>
--- End preview ---
Ready to write? (yes / no / edit)
Wait for the user's explicit response:
yes / go: proceed to Step 6 for THIS decision.no / skip: mark this decision as skipped in the sync log; move to the next candidate.edit: ask the user what to change in the preview content, regenerate, re-present, ask again.yes to all writes (literal): authorize this AND all remaining decisions in the candidate list without per-decision confirmation. This is the ONLY way to batch — explicit user opt-in per ADR-016. The exact phrase "yes to all writes" must appear in the user's reply; partial forms like "yes to all" or "yes all" do NOT trigger the batch carve-out (per the retro 2026-05-19 finding aligning SKILL.md to ADR-016's literal-phrase requirement).cancel: abort the entire sync run; nothing else gets written.no; re-prompt.Per ADR-016: "Do NOT proceed on implicit consent. Do NOT batch multiple writes behind a single yes unless the user explicitly says 'yes to all writes' in this invocation."
Call the connected ~~docs MCP's write tool with the resolved target + proposed content.
For each MCP:
pages.create (new page) or blocks.children.append (append to existing page). Set parent to the target page; populate properties.title from decision title.confluence.pages.create or confluence.pages.update. Set space + parent per target.documents.batchUpdate with InsertText requests appending to the target doc..md or .txt) at the resolved path; vendor-specific tool name.On success, capture:
On failure, surface the error and ask the user: continue with remaining decisions? Abort?
For each successfully synced decision:
Update the decision file's frontmatter to record the sync — add or update:
synced_to_~~docs:
- target: <destination URL>
vendor: <notion|atlassian|box|egnyte|google docs>
synced_at: <ISO timestamp>
operation: <create|append|update>
This is the only modification to the source file — content is unchanged; only frontmatter records the sync state.
Append to logs/sync-decisions.md:
## <YYYY-MM-DD HH:MM> — <vendor>
- **<decision-slug>** → [<destination URL>](<destination URL>) (<operation>)
Source: `decisions/<slug>.md`
Size: <N> chars
<repeat per synced decision>
If a decision was skipped (no response), log it too with status: skipped for audit traceability.
Summary to user:
Sync complete: <N synced> / <N skipped> / <N failed>
Synced to <vendor> (<target>):
- <slug>: [<destination URL>](<destination URL>) <create|append>
- <slug>: ...
Skipped (user declined):
- <slug>
- <slug>
Failed (MCP errors):
- <slug>: <error message>
Sync log: logs/sync-decisions.md
synced_to_~~docs: frontmatter field changes locally; the markdown body is untouched./sync-decisions <slug> --target <url1> then /sync-decisions <other-slug> --target <url2>.logs/sync-decisions.md for audit traceability.logs/sync-decisions.md + update the same synced_to_~~docs: frontmatter shape.synced_to_~~docs: frontmatter convention is new in v2.18.0. Documented in CONFIG.md schema section (added in Phase 3a)./audit-knowledge — synced decisions are no different from unsynced for audit purposes. The synced_to_~~docs: field is informational, not consumed by audit routing._project-knowledge/ git-based team sharing. That mechanism (v2.13.0) is for per-repo team-mate sharing; /sync-decisions is for org-wide wiki / docs publishing. Both can run in parallel./sync-rules or /sync-references skill could follow the same pattern if external mirroring of other knowledge artifacts is wanted. ADR-016's preamble template ports forward.npx claudepluginhub mikeprasad/aria-knowledge --plugin aria-knowledgeBatch-reviews personal knowledge files and IDEAS-BACKLOG entries for promotion to team-shared project knowledge. Recommends target destinations and lets user approve, modify, or skip.
Records canonical decisions, facts, or preferences in shared Papyrus workspace with automatic deduplication on (type, canonical_name). Returns action and papyrus_id for multi-agent coordination and ADR capture.