aria-knowledge

/context — On-Demand Knowledge Retrieval

Query the knowledge tag index and load relevant promoted files into the conversation context.

Runtime Gate (per ADR-094)

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 /context 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:context.

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 /context from a non-Code runtime.

Behavior is largely the same in both runtimes; for the Cowork-native variant (reads index.md from the attached knowledge folder via persistent grant), use /aria-cowork:context.

Use /aria-cowork:context instead? (y / n)

Wait for an explicit reply:

• y / yes — Use the Skill tool to invoke aria-cowork:context 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.
• No response / any other reply — Treat as "do not proceed" and exit cleanly without running either variant.

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.

Step 0: Resolve Config

Read ~/.claude/aria-knowledge.local.md and extract:

• knowledge_folder — required
• projects_enabled — default false
• projects_list — default empty (only relevant if projects_enabled: true)
• projects_shared_knowledge — default empty; comma-separated list of project tags enabled for shared knowledge. When non-empty, also surface team-shared files indexed under ## Team-Shared Tag Index. Tags not in this list are not surfaced even if they appear in the index.

Parse projects_list into a tag→path map. The format is comma-separated tag:path pairs (e.g., proj-a:path/to/proj-a,proj-b:proj-b). Tags are used to identify project-specific files; paths are not used by /context (they're for CWD detection in other skills).

If the config file doesn't exist, stop: "aria-knowledge is not configured. Run /setup to get started."

Step 1: Read Index

Read {knowledge_folder}/index.md.

If the file doesn't exist, stop: "No knowledge index found. Run /index to build it."

Parse the index to extract:

• ## Projects section — project name/key and their relevant tags
• ## Known Tags section — the canonical tag list
• ## Tag Index section — tag → file mappings for known tags
• ## Other Tags section — tag → file mappings for freeform tags
• ## Team-Shared Tag Index section — tag → team-shared file mappings (only when projects_shared_knowledge is a non-empty list); paths are absolute-from-home (~/Projects/...) and entries carry a [project: ..., scope: ...] annotation. Section may be absent if no team-shared files exist or the list is empty.

Step 2: Parse Query

The user's argument is a space-separated list of tags with optional AND keyword.

Parsing rules:

• Split on spaces
• If the token AND (case-insensitive) appears, use intersection mode — a file must have ALL specified tags
• Otherwise, use union mode (default) — a file matches if it has ANY of the specified tags
• Remove AND tokens from the tag list

Examples:

• /context stripe → tags: [stripe], mode: OR
• /context api pagination → tags: [api, pagination], mode: OR
• /context api AND pagination → tags: [api, pagination], mode: AND
• /context ss → tags: [ss], mode: OR (with project expansion)

If no argument provided, stop: "Usage: /context <tag1> [tag2] [AND tag3]. Run /index to see available tags."

Step 2.5: Resolve Aliases (added 2.16.0)

After parsing the query into tokens (Step 2) but BEFORE project expansion (Step 3), resolve any aliases.

Source: the alias map is encoded in index.md's ## Known Tags section as [aliases: ...] annotations on canonical tag entries. Parse that section to build a flat alias → canonical map. If no aliases are declared (no [aliases: ...] annotations exist), skip this step entirely.

Resolution: for each token t in the parsed query, look up t in the alias→canonical map. If matched, replace t with its canonical form. Record the resolution.

Notification: for each resolution, emit one line BEFORE the Step 3 "Expanded …" notification:

Resolved `rn` → `react-native`

Order matters: alias resolution runs BEFORE project expansion. If seer → ss is an alias and ss is a project tag, querying /context seer resolves to ss first; Step 3 then expands ss to its relevant tags.

Unidirectional: resolution is alias → canonical only. Querying the canonical does NOT match alias-only declarations (i.e., querying react-native won't surface files that only declare alias rn).

Step 3: Project Tag Expansion

For each tag in the query, check if it matches a project key in the ## Projects section (e.g., ss, cs, df, aria).

If a tag matches a project:

1. Keep the project tag itself in the search
2. Also add all of that project's "Relevant tags" to the search
3. Notify the user:

`` Expanded ss to include: api, django, nextjs, stripe, supabase, database, deployment ``

Project expansion only applies in union (OR) mode. In AND mode, project tags are treated as literal tags (a file must be tagged ss specifically).

Step 4: Match Files

File discovery has three sources: the index ## Tag Index and ## Other Tags sections (cross-project tagged files), the filesystem (project-specific files under projects/{tag}/**), and the index ## Team-Shared Tag Index section (team-shared files in code repos under _project-knowledge/). All three contribute to the result set; results are categorized so Step 5 can present them grouped.

Matching rule (extended 2.16.0): for any source, a query token t matches a file f if either:

1. t equals a tag declared by f (existing behavior), OR
2. t.lower() (with hyphens stripped) appears as a substring of any phrase in f's semantic-hints: frontmatter (also lowercased + hyphen-stripped).

The ## Semantic Hints Index in index.md is the discovery surface for hint matches — Step 4a scans both ## Tag Index / ## Other Tags AND ## Semantic Hints Index for query-token matches. AND/OR mode applies per-token: each token can satisfy independently via tag OR hint.

When a file matches via hint rather than tag, append [hint: <phrase>] to the Step 5 result render so the user can see why the file was surfaced.

Step 4a: Index-driven matches (cross-project)

Scan the ## Tag Index and ## Other Tags sections for entries matching the query tags.

Exclude files whose path starts with projects/ — those are project-tier files, handled by Step 4b. This prevents duplicate listings when a project-tier file is discoverable via both its YAML tag (in the index) and its path (via Glob in Step 4b). Since /index (Phase 4+) scans project-tier files and adds them to the Tag Index with path-derived tags, a project file tagged agentic-ui would otherwise appear