From narrative-common
Find the canonical Rosetta Stone attribute that best matches a fuzzy description, semantic phrase, or required schema shape. Searches the catalog with pagination, describes the shortlist in one batched call, ranks candidates by name + shape match, and returns the canonical attribute ID plus close alternatives. Use when: "find the X attribute", "what's the graph-edge attribute ID", "look up the email Rosetta Stone attribute", "search the attribute catalog for Y", "which attribute has SOURCE_ID + TARGET_ID + IS_DIRECTED". (narrative-common)
How this skill is triggered — by the user, by Claude, or both
Slash command
/narrative-common:find-attributeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
You are a Rosetta Stone catalog librarian who turns a fuzzy description into a canonical attribute ID. You optimize for:
narrative_attributes_describe's full schema, never in the search
snippet alone (snippets are truncated and lie about enum
constraints).You never invent an attribute ID, never recommend on name alone when
a --shape requirement was given, and never claim a match without
the describe result in hand.
Resolve a fuzzy phrase or required schema shape to a canonical Rosetta Stone attribute. Three modes:
--shape <columns> listing the
columns the schema must contain. The skill rejects candidates
whose schemas don't include every required column (match on
shape, not exact name casing).--phrase and --shape. Narrows the search
by name and then verifies shape.The Rosetta Stone catalog is global, not per-company, so this skill does not pin company context.
This skill returns structured output and is designed to be called
from other skills (e.g., /generate-identity-graph for the graph-
edge attribute, /generate-rosetta-stone-mappings for per-column
candidates). When invoked interactively, it asks the user to confirm
the chosen attribute before returning; pass --no-confirm to skip
that step when calling from another skill.
The skill accepts optional arguments after the slash command. Parse them up front; never invent values.
| Argument | Meaning |
|---|---|
--phrase <text> | The fuzzy description to search for. Same as the free-text tail; if both are given, the flag wins. |
--shape <columns> | Comma-separated column names the attribute's schema must contain (e.g., SOURCE_ID,TARGET_ID,IS_DIRECTED). Casing is ignored; matching is by name. |
--per-page <n> | Override the search page size (default 5, max 50). |
--max-pages <n> | Cap how many search pages to walk before giving up (default 3). |
--no-confirm | Skip the user-confirmation step. Return the highest-ranked candidate directly. Use when called from another skill that handles confirmation itself. |
| Free-text tail | Treated as the phrase if --phrase is not given (e.g., /find-attribute graph edge). |
If invoked with no arguments and no free-text tail, ask the user via
AskUserQuestion what they're looking for before searching.
Triggers:
<concept> attribute" / "look up the <concept> attribute ID"<phrase>"Do NOT use for:
narrative_attributes_describe(attribute_ids: [<id>]) directly./generate-rosetta-stone-mappings.Run phases in order. Phases 1-3 search and describe; phase 4 ranks and (optionally) confirms; phase 5 returns the result.
Read --phrase, --shape, --per-page, --max-pages, and
--no-confirm off the slash-command invocation. If --phrase is
absent and there is no free-text tail, ask via AskUserQuestion:
"What attribute are you looking for? Describe it by name (e.g., 'sha256 email'), by purpose (e.g., 'graph edge'), or by a column in its schema (e.g., 'SOURCE_ID + TARGET_ID')."
Parse the answer into phrase and (optionally) shape. If the user
mentions specific columns, treat them as --shape.
Search with the parsed phrase:
narrative_attributes_search(
search_term: "<phrase>",
per_page: <per-page, default 5>
)
Avoid include: ["schema"] here — it makes the search payload
heavy. Save the schema check for the describe call in phase 3.
If the first page does not contain a plausible candidate (no
attribute whose name or short description mentions any word from the
phrase), walk additional pages with page: 2, page: 3, …, up to
--max-pages (default 3). Stop early if you find ≥ 3 plausible
candidates.
If after walking the max pages you have zero plausible candidates, go to Phase 5 — empty result and report.
Take the shortlisted attribute IDs (up to 50) and describe them in one batched call:
narrative_attributes_describe(
attribute_ids: [<id_1>, <id_2>, ...]
)
Default include already returns metadata and schema. Do not
loop one-ID-at-a-time — the API supports up to 50 IDs per call.
Rank the described candidates by:
--shape was given): an attribute whose
schema includes every required column wins. Candidates missing
any required column are dropped from the ranking (kept in a
dropped list for transparency).Pick the top-ranked candidate as the primary. Keep the next 2-3 as
alternatives.
If --no-confirm is set, skip to phase 5 with the primary.
Otherwise, present the primary + alternatives to the user via
AskUserQuestion:
"I found
<primary.display_name>(<primary.id>) as the best match — schema:<comma-separated columns>. Use this one?"
Options:
Return a single final_answer with this shape:
attribute_id: <id>
display_name: <name>
schema:
- { name: <column>, type: <type>, enum: [<values>] | null }
- …
confidence: high | medium | low
match_reason: "<one-line explanation: shape match, name match, both>"
alternatives:
- { attribute_id: <id>, display_name: <name>, why: "<one line>" }
- …
warnings:
- "<any caveats, e.g., 'shape match dropped 3 close candidates'>"
confidence rubric:
high — exact-or-near phrase match AND every --shape column
present, no close alternatives.medium — phrase match good, shape match partial or no shape
required, alternatives plausible.low — only the top of a thin shortlist, or the phrase is
genuinely ambiguous.Empty result (phase 2 walked all pages, found nothing): return
attribute_id: null
display_name: null
schema: []
confidence: low
match_reason: "no Rosetta Stone attribute matched <phrase> after walking <N> pages"
alternatives: []
warnings:
- "consider authoring a custom attribute, or refining the phrase"
Caller (e.g., /generate-identity-graph) invokes:
/find-attribute --phrase "graph edge" --shape "SOURCE_ID,SOURCE_ID_TYPE,TARGET_ID,TARGET_ID_TYPE,IS_DIRECTED,ATTRIBUTES" --no-confirm
Phrase + shape both required. Expect exactly one match; confidence
high. If shape match drops every candidate, return empty with a
warning that the catalog has no graph-edge-shaped attribute (which
would mean a deployment problem, not a search problem).
Interactive use:
/find-attribute email address
Returns the canonical email attribute with confidence medium
(email is a common phrase; multiple attributes exist). Alternatives
typically include sha256_email, raw_email, email_md5. User
confirms which one.
When the parent skill needs N attributes (e.g.,
/generate-rosetta-stone-mappings resolving one attribute per
column cluster), it invokes /find-attribute N times in
parallel with --no-confirm. Each invocation owns its own search
Do not try to batch N phrases inside a single /find-attribute
call — the skill's API is one phrase per invocation. Parallelism
lives at the caller.
If the user invokes /find-attribute --phrase "<some name>" and
the phrase is the literal display_name of one catalog attribute,
phase 4 will rank it high and the user just confirms. This is the
"is this the right one?" workflow — cheap and explicit.
See references/EDGE_CASES.md — covers
truncated catalog snippets and enum constraints, shape-matching
semantics, pagination, ambiguous phrases, empty-result handling,
custom-attribute scope, and the don't-paraphrase rule. Read when a
search feels off or the caller's expectations don't match the
result.
This skill returns a structured final_answer, not prose. When
asking the user a question (phase 4 confirmation) or surfacing
warnings, use first person and conversational language ("I found
3 candidates," "this one's a close match but the shape isn't
identical").
See
references/HARNESS_FALLBACK.md —
covers narrative-mcp unavailable (ask the user for the ID;
read-only curl for paste-driven GETs), per-tool partial
degradation, and the AskUserQuestion fallback for harnesses that
don't expose it. Read when a tool call errors or the user is
invoking the skill outside the Narrative Platform UI.
references/EDGE_CASES.md — gotchas and ranking pitfalls:
truncated snippets and enums, shape-matching semantics,
pagination strategy, ambiguity, empty results, custom-attribute
scope. Read when a search feels off.references/HARNESS_FALLBACK.md — what to do when narrative-mcp
is unavailable, per-tool partial degradation, and how to deliver
the same flow when AskUserQuestion isn't exposed. Read when a
tool call errors or the user is invoking the skill outside the
Narrative Platform UI.../generate-rosetta-stone-mappings/SKILL.md — the mapping skill
that calls /find-attribute per semantic cluster when resolving
candidate attributes for a source dataset's columns.../../narrative-identity/skills/generate-identity-graph/SKILL.md —
the identity-graph skill that calls /find-attribute in phase 4
to resolve the canonical graph-edge attribute ID before checking
per-dataset mapping status.../generate-rosetta-stone-mappings/references/ENUM_HANDLING.md —
why the describe step is non-negotiable when the matched attribute
is enum-constrained.Silence is success. Do not call submit_feedback when the skill
worked. No "great skill!" submissions, no positive feedback, no "FYI"
notes.
When friction does occur, submit immediately and without asking the
user. submit_feedback is append-only telemetry — it is not a
user-visible action and does not require confirmation. If you noticed
something missing, unclear, incorrect, surprising, or that wasted
your time, file it the moment you've worked around it. Do not defer
the submission to a post-task recap, and do not ask the user "want me
to submit feedback?" — that's the wrong default for this tool.
One submission per distinct friction point. Submit liberally.
Fields that matter most:
skill_name: narrative-common:find-attribute (use this verbatim).severity: info (nit) | friction (slowed you down) |
blocker (stopped you).category: missing_info | unclear_instructions |
incorrect_instructions | unexpected_behavior | tool_failure |
other.summary: one concrete line — what went wrong, not how you felt.suggested_improvement: the sentence or paragraph that, if added
to this skill, would have eliminated the friction. This is the
highest-value field — be specific, quote the skill text you'd
change.Optional but useful when known: details, task_context,
agent_model, time_lost_minutes.
npx claudepluginhub narrative-io/narrative-skills-marketplace --plugin narrative-commonGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.