Recipe · Query alloy directly

Goal: pull a specific alloy doc into your session without going through a role agent. Useful when you want platform truth — an SDK convention, a pattern, the matrix — and don't need analysis or a generated artifact.

Time: seconds · Phase: anytime · How: invoke skill:e11-knowledge with a query key, or pick [QK] Query Knowledge from any agent's menu

Prerequisites

• @engineering11/alloy installed in the project: npm install @engineering11/alloy. Without it, skill:e11-knowledge halts with an install instruction.

For the full query-key cheatsheet and citation rules, see Knowledge layer.

The eight most-asked queries

list:sdks                     # what domain SDKs exist (Tier 2 catalog)
list:backend-apis             # what infrastructure APIs exist (Tier 1 catalog)
sdk:<name>                    # an SDK's overview
sdk:<name>:backend-using      # how to consume an SDK from a backend
sdk:<name>:frontend-using     # how to consume an SDK from a frontend
pattern:<name>                # multi-tenancy, CQRS, error-handling, etc.
matrix:unit                   # the selection matrix (always/implies edges; matrix:sdk = back-compat copy)
convention:react-conventions  # repo-wide convention docs

Walkthrough

You: skill:e11-knowledge sdk:access:backend-using

Skill: Resolving via the ladder (MCP → cache → package-source)…

     [alloy:sdk:access:backend-using] sources/sdks-nodejs/sdks/access/backend-using.md
     ---
     # Using @engineering11/access - Backend

     The Access SDK provides tenant scoping, role gates, and the @CrudAuth
     decorator for permission checks.

     ## TenantScope
     ...
     ## @CrudAuth
     ...
     ---
     Cite as: alloy://sources/sdks-nodejs/sdks/access/backend-using.md
     [resolved] rung=package-source corpus=<version> view=<view>
     [pin] <pinned|unpinned line>

The skill returns the file contents verbatim with a citation header and a marker envelope. Whoever invoked it - you, or another skill - decides what to use. Cite the exact Cite as: path it returns; never construct a corpus path. Activation is deliberately cheap (no config load, no greeting): it's a retriever built to be called constantly.

Common patterns

Surveying what the platform offers

skill:e11-knowledge list:sdks
skill:e11-knowledge list:backend-apis

Two queries together give the full "what's available" view. This is exactly what e11-prd's Platform Capability Map and e11-architecture's SDK composition do at the start of their runs.

Pre-loading before editing platform code

e11-dev-story, e11-dev-flow, and e11-dev-auto do this automatically (the capability-driven pre-load), but you can front-run it:

skill:e11-knowledge sdk:auth:backend-using
skill:e11-knowledge sdk:user:backend-using

Frontend component reconnaissance

skill:e11-knowledge sdk:files:frontend-using
skill:e11-knowledge convention:react-conventions
skill:e11-knowledge convention:component-patterns

Resolving the SDK matrix

The bootstrap wizard parses this to compute always/implies edges; you can preview it:

skill:e11-knowledge matrix:unit

Grounding technical research

[TR] Technical Research consults alloy first; you can pre-empt it:

skill:e11-knowledge foundation:platform-model
skill:e11-knowledge infra:cloud-run-conventions
skill:e11-knowledge pattern:multi-tenancy

Reading backend patterns not yet in alloy

Four reserved upstream-skill keys cover material that lives only in the sdks-nodejs skill set for now:

skill:e11-knowledge pattern:backend-shared
skill:e11-knowledge pattern:backend-standards
skill:e11-knowledge pattern:gen-microservice
skill:e11-knowledge pattern:gen-sdk

These cite as sdks-nodejs-skill://<file>.md — different from alloy://.

What happens when a doc is missing

You: skill:e11-knowledge sdk:nonexistent

Skill: [alloy:sdk:nonexistent] NOT FOUND in corpus
     Fallback: @engineering11/nonexistent source at
       /Users/you/project/node_modules/@engineering11/nonexistent/src

     Package source also not found.
     Suggestion: query list:sdks, list:backend-apis, or list:microservices
     to enumerate what exists.

When the SDK exists but its alloy doc is thin or missing, the skill falls back to pointing at the package source on disk. Read that directly — @engineering11/<pkg>/src/index.ts first, then src/**/index.ts.

Point it at your own corpora

e11-knowledge has a customization surface (.foundry/custom/e11-knowledge.toml) with two fields worth knowing:

• corpus_root — where the corpus lives. Remap for monorepos that hoist node_modules, vendored checkouts, or a pre-release corpus build.
• extra_query_keys — team-extensible query prefixes, checked before the built-in tables:

[[workflow.extra_query_keys]]
id = "runbook"
path_template = "runbooks/<name>.md"
root = "{project-root}/docs/ops"

Now skill:e11-knowledge runbook:rotate-keys resolves docs/ops/runbooks/rotate-keys.md — same citation discipline, your content. Details: Knowledge layer § customizing.

Gotchas

• Vocabulary is discovered, not memorised. Which categories and list: names are live depends on your pinned view; ask the corpus (the manifest tool or the loaded manifest) rather than assuming a fixed set.
• Smart routing makes sdk: cross-tier. A query like sdk:datastores smart-routes to the backend-api base (Tier 1) when no Tier 2 doc exists. Use api:datastores to assert Tier 1 explicitly, or microservice:<name> for Tier 3.
• Subdoc names differ by tier. Tier 2 uses backend-building / backend-using / frontend-building / frontend-using / shared. Tier 1 uses building / using. Smart routing translates between them, but a Tier-2-only subdoc on a Tier-1 package (e.g. sdk:datastores:frontend-using) falls back to NOT FOUND.
• Citations use the resolved path. Cite the exact alloy://<path> the skill's Cite as: line returns - never a constructed one. A legacy flat V1 path resolves to a redirect tombstone; cite the successor path the skill returns.
• The skill is read-only. It never modifies alloy content. If you want to add a doc, that's a PR to the alloy repo, not a Foundry change (or an extra_query_keys corpus of your own).

Source

Skill: e11-knowledge/SKILL.md · upstream resolver: e11-sdks-nodejs/SKILL.md, e11-sdks-react/SKILL.md

See also: Knowledge layer (full cheatsheet) · Concepts §4.