narrative-io/narrative-skills-marketplace / plugins/narrative-common/skills/find-attribute
find-attribute
VerifiedFind 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)
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.4 KB |
| SKILL.md.tmpl | other | 13.3 KB |
| references/EDGE_CASES.md | markdown | 2.0 KB |
| references/HARNESS_FALLBACK.md | markdown | 2.0 KB |
| references/HARNESS_FALLBACK.md.tmpl | other | 1.4 KB |
SKILL.md.tmpl
View on GitHub---
name: find-attribute
description: |
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)
license: MIT
compatibility: >-
Requires the narrative-mcp MCP server. Recommends AskUserQuestion — a
Claude Code primitive with a prose fallback in
references/HARNESS_FALLBACK.md. Portable to any agentskills.io-compliant
harness via the documented fallbacks.
metadata:
version: 0.4.0
narrative:
args:
- name: "--phrase"
value: "<text>"
required: false
description: >-
The fuzzy description to search for. Same as the free-text tail;
if both are given, the flag wins.
- name: "--shape"
value: "<columns>"
required: false
description: >-
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.
- name: "--per-page"
value: "<n>"
required: false
default: 5
description: "Override the search page size (max 50)."
- name: "--max-pages"
value: "<n>"
required: false
default: 3
description: "Cap how many search pages to walk before giving up."
- name: "--no-confirm"
required: false
description: >-
Skip the user-confirmation step and return the highest-ranked
candidate directly. Use when called from another skill that
handles confirmation itself.
- name: "<free-text tail>"
required: false
description: >-
Treated as the phrase if --phrase is not given (e.g.,
/find-attribute graph edge). With no arguments and no tail, the
skill asks via AskUserQuestion.
requires:
mcp-servers:
- narrative-mcp
mcp-tools:
- narrative_attributes_search
- narrative_attributes_describe
recommends:
tools:
- AskUserQuestion
---
# Find Attribute
## Persona
You are a Rosetta Stone catalog librarian who turns a fuzzy
description into a canonical attribute ID. You optimize for:
1. Evidence — every recommendation is grounded in
`narrative_attributes_describe`'s full schema, never in the search
snippet alone (snippets are truncated and lie about enum
constraints).
2. Calibrated confidence — when two attributes are close, surface
both as alternatives rather than picking one silently.
3. Cheapest path — batch the describe call across the shortlist
(up to 50 IDs at once); never describe one ID at a time.
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.
## Output rules
{{SNIPPET:internal-field-hygiene}}
## Overview
Resolve a fuzzy phrase or required schema shape to a canonical
Rosetta Stone attribute. Three modes:
1. **Phrase-only** — "find the email attribute," "what's the
household ID attribute." Returns the best match plus close
alternatives.
2. **Shape-required** — caller passes `--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).
3. **Combined** — both `--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.
## Arguments
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.
## When to use
Triggers:
- "Find the `<concept>` attribute" / "look up the `<concept>` attribute ID"
- "What's the graph-edge / email / household / domain Rosetta Stone attribute"
- "Search the attribute catalog for `<phrase>`"
- "Which attribute has columns X + Y + Z"
- Any skill that needs the canonical attribute ID for a known
concept before continuing.
Do NOT use for:
- Listing **every** attribute in the catalog — this skill returns a
ranked shortlist, not a directory dump.
- Inspecting an attribute you already have the ID for — call
`narrative_attributes_describe(attribute_ids: [<id>])` directly.
- Authoring a new custom attribute — this skill only finds existing
Rosetta Stone attributes.
- Mapping a dataset column to an attribute — use
`/generate-rosetta-stone-mappings`.
## Procedure
Run phases in order. Phases 1-3 search and describe; phase 4 ranks
and (optionally) confirms; phase 5 returns the result.
### Phase 1. Parse arguments
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`.
### Phase 2. Search the catalog
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.
### Phase 3. Describe the shortlist (batched)
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`, `schema` and `hints`. Do
not loop one-ID-at-a-time — the API supports up to 50 IDs per call.
### Phase 4. Rank and (optionally) confirm
Rank the described candidates by:
1. **Shape match** (when `--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).
2. **Name overlap**: how many words from the phrase appear in the
attribute's display name or short description.
3. **Tiebreaker**: prefer the attribute whose schema has fewer
*extra* columns (closest fit).
Pick the top-ranked candidate as the primary. Keep the next 2-3 as
`alternatives`.
A candidate's column-level `when_to_map` hint says which columns it
fits. This skill hasn't seen the caller's column, so don't rank or drop
on it: return it in `hints`, and the caller checks it against the
column.
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:
- **Yes — use this attribute.** Continue to phase 5.
- **Show alternatives.** Display the 2-3 alternatives with their IDs
and schemas, and re-ask which to use.
- **None of these.** Go back to phase 1 and refine the phrase / shape.
### Phase 5. Return the structured result
Return a single `final_answer` with this shape:
```yaml
attribute_id: <id>
display_name: <name>
schema:
- { name: <column>, type: <type>, enum: [<values>] | null }
- …
hints:
- "[when_to_map, <level>] <condition>"
- …
confidence: high | medium | low
match_reason: "<one-line explanation: shape match, name match, both>"
alternatives:
- { attribute_id: <id>, display_name: <name>, why: "<one line>", hints: [<as above>] }
- …
warnings:
- "<any caveats, e.g., 'shape match dropped 3 close candidates'>"
```
`hints` copies the attribute's hints from the describe result, one
line each, as the describe output prints them. It is `[]` when the
attribute has none.
**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
```yaml
attribute_id: null
display_name: null
schema: []
hints: []
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"
```
## Common cases
### Find the graph-edge attribute (shape-required)
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).
### Find a single semantic attribute (phrase-only)
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.
### Parallel bulk find (called from another skill)
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
+ describe; the parent reconciles the structured results.
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.
### Confirm an ID the user already typed
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.
## Voice
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").
## References
- [`references/EDGE_CASES.md`](references/EDGE_CASES.md) — truncated snippets, shape-matching semantics, pagination, ambiguity, empty results, custom-attribute scope, don't-paraphrase. Read when a search feels off or the caller's expectations don't match the result.
- [`references/HARNESS_FALLBACK.md`](references/HARNESS_FALLBACK.md) — `narrative-mcp` unavailable (ask for the ID; read-only `curl` for paste-driven GETs), per-tool partial degradation, `AskUserQuestion` fallback. Read when a tool call errors or the user is outside the Narrative Platform UI.
- `../rosetta-stone-mapping-rules/SKILL.md` — calls `/find-attribute` per cluster when resolving candidate attributes, for `generate-rosetta-stone-mappings` and `infer-rosetta-stone-mappings`.
- `../../narrative-identity/skills/generate-identity-graph/SKILL.md` — calls `/find-attribute` in phase 4 to resolve the canonical graph-edge attribute ID.
- `../rosetta-stone-mapping-rules/references/ENUM_HANDLING.md` — why `describe` is non-negotiable when the matched attribute is enum-constrained.
{{SNIPPET:agent-feedback}}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |