/enrich-capability

The latent half of the three-layer ingest pipeline. Where /ingest-source orchestrates the workflow and auxiliar ingest handles the deterministic transforms, this skill does the judgment: reading an upstream README, holding contradictions in mind, and synthesizing what an agent in-loop would search for to find this capability.

This is the "diarization" step from memos/Arquitetura.pdf — the model reads everything about a subject and writes a structured profile. No keyword extractor produces this. No embedding similarity finds the right choose_if line. The model has to actually read the README and make a judgment.

Parameters

When to invoke

• Step 4 of /ingest-source (the canonical caller).
• A user wants to manually enrich one staged record for testing.
• A previously-enriched record needs refreshing because the upstream

README changed substantially.

What the skill writes

These are the fields agents need to find and pick the capability — the ones the upstream registry can never supply.

Optionally, if the README makes it unambiguous:

• cost.type flip from unknown to free / freemium / usage_based.

Only update if there's an explicit pricing statement in the README, not a guess.

• risks[] append — material risks the README discloses (rate limits,

scope limits, lock-in, etc.). Skip if not stated.

• compliance[] append — explicit SOC2 / HIPAA / LGPD claims only.

Must-be-grounded fields (read this before writing the YAML)

The 2026-05-14 graduation gate ran against 135 wave-1 enriched records and FAILed 11 on hallucinations the enrichment confidently asserted without README support. The pattern was systemic — 7 of 87 PP records claimed license: MIT despite the README mentioning no license at all. The same shape applies to runtime versions and risk specifics.

These fields can only be written when the upstream source literally contains the claim. If you don't see it verbatim or near-verbatim in the README / package.json / pyproject.toml / equivalent, leave the field unset (or as null):

The graduation gate (src/auxiliar/curator/graduation.py) reads the README and asks Claude Sonnet 4.6 specifically about these fields. Records that fail go back to experimental status and need re-enrichment — expensive. Better to leave a field unset than to fail graduation later.

The skill MUST NOT

• Invent repository, cost, risks, compliance values not in the

source.

• Assert license, deps.minimum_runtime, or specific risks[]

numerics / codes / dates without literal upstream evidence (see the table above). The graduation gate will catch and reject these.

• Flip experimental: false — that's the orchestrator's job after

curator smoke passes.

• Write to data/capabilities/ directly. Always operate on the staging

YAML.

Procedure

Step 1 — Read the thin record + understand the upstream

Read the staging YAML. Note:

• provenance — tells you which source this came from.
• repository, external_homepage, mcp_registry_id — your entry

points for the upstream fetch.

• description — usually one line of upstream marketing copy; helpful

but rarely sufficient.

Step 2 — Fetch the README

Use the deterministic tool of choice (gh api, raw.githubusercontent.com, WebFetch). Cap at MAX_FETCH_KB. If the upstream has no README, also fetch any docs/ index and the first 100 lines of package.json / pyproject.toml / cargo.toml.

If after this you still can't tell what the capability does, return INSUFFICIENT_DATA and let the orchestrator mark the record for retry. Do not guess.

Step 3 — Diarize

Hold the thin record + the README + any sample interactions in mind at once. Ask:

• What jobs does an agent in-loop want done that this answers?

Concrete tasks, not abstract categories. Write 5–12 jtbd_tags.

• What would an agent type into a search box? Mix short keyword

phrases with full-sentence queries. Write 8–15 aliases_search. If the agent's user is likely Brazilian-Portuguese-speaking (BR data, PT documentation), include 2–5 PT-BR entries — the GPT-5 agent-journey simulation showed models auto-translate to PT-BR for Brazilian topics even when the input is English.

• When SHOULD an agent pick this? Write one paragraph for

choose_if. Name an alternative class.

• When SHOULDN'T an agent pick this? Write one paragraph for

avoid_if. Name a scope limit the README states.

For the framework's "says vs actually building" gap-check: if the upstream description and the README disagree about scope (e.g., README shows much narrower coverage than the marketing line), call that out in risks[] with category scope.

Step 4 — Write the fields back

Edit the staging YAML in-place. Preserve existing fields exactly. Append the new ones in this order: jtbd_tags, aliases_search, categories, choose_if, avoid_if. If you appended to risks[], keep severity correct: low for scope limits, medium for rate limits or lock-in, high only when the README admits production- unsafe gaps.

Step 5 — Validate

Round-trip the YAML through Capability.model_validate (Python REPL or python -m auxiliar.cli.ingest dedup --dry-run against a temp dir). If validation fails, revert and return the error to the orchestrator.

Step 6 — Report

Return a short summary:

• Fields written: [list]
• Cost updated: yes/no
• Risks appended: N
• Read README from: <URL>
• Word count of README processed: N

What good enrichment looks like

A pre-enrichment thin record (from MCP Registry):

id: ac-tandem-docs-mcp
element_type: mcp
name: ac.tandem/docs-mcp
description: Remote MCP server for Tandem docs, install guides, SDKs, workflows, and agent setup help.
cost:
  type: unknown
last_verified: '2026-05-11'
verification_method: mcp-registry-ingest-2026-05-11
page_url: https://auxiliar.ai/mcp/ac-tandem-docs-mcp/
provenance: mcp-registry
experimental: true
mcp_registry_id: ac.tandem/docs-mcp
repository: https://github.com/frumu-ai/tandem
external_homepage: https://github.com/frumu-ai/tandem

Post-enrichment (illustrative — not authoritative):

# ... all fields above kept verbatim ...
jtbd_tags:
  - tandem-docs-lookup
  - read-tandem-install-guides
  - tandem-sdk-reference
  - find-agent-setup-help
  - mcp-host-config-docs
aliases_search:
  - tandem docs
  - how do I install tandem
  - tandem MCP server agent setup
  - I need to read the tandem SDK reference inside my agent
  - tandem workflow documentation accessible from claude desktop
categories:
  - documentation
  - agent-tooling
choose_if: >-
  You're inside a Claude Desktop or Cursor session and need to look up
  Tandem-specific install guides, SDK reference, or agent-setup workflows
  without leaving the session. Streamable-HTTP transport keeps roundtrip
  fast inside the host.
avoid_if: >-
  You need Tandem's product features themselves (the docs MCP is read-only
  reference). Also avoid if the agent already has the Tandem docs cached —
  no marginal benefit and adds one MCP to the registration surface.

What this skill does NOT do

• Score the capability against alternatives (that's the curator fleet).
• Write the live data/capabilities/<slug>.yml (that's `auxiliar

ingest promote` after the orchestrator approves).

• Fetch arbitrary parts of the internet — only the upstream

repository / homepage / docs index. Discovery isn't the job here.

Reading list

• docs/proposals/three-layer-ingest.md — the architecture
• memos/Arquitetura.pdf — diarization (step 5 in the framework)
• docs/proposals/capability-schema.md — what fields exist + invariants
• data/capabilities/*.yml — read 5–10 well-enriched hand-curated

records before writing your first enrichment, to align style and depth