/profile-dataset

name: profile-dataset
description: |
  Produce a coverage & quality profile of a Narrative dataset (or access
  rule): row count, per-column null/fill rate, cardinality, ranges,
  top-values, inferred column shape, and quality flags. Reads bundled
  stats + sample first, recovers missing/stale stats by configuring and
  recalculating them, and escalates to a cheap `/write-nql` query only
  for a measure no stat can provide. Descriptive, not prescriptive.
  Use when: "profile dataset N", "what does dataset N look like",
  "coverage and quality of <dataset>", "what id types does N emit",
  "null rates / cardinality for <dataset>", "is this dataset's stats
  fresh".
  (narrative-common)
license: MIT
compatibility: >-
  Requires the narrative-mcp MCP server (no MCP → cannot profile).
  Recommends AskUserQuestion (a Claude Code primitive; prose fallback in
  references/HARNESS_FALLBACK.md), the `/write-nql` sibling skill for the
  custom-measure escalation, and the narrative-knowledge-base MCP server.
  Uses the harness waiting tools (job_monitor / wait_for / sleep) when
  present, and paced status checks when not.
  Portable to any agentskills.io-compliant harness via the documented
  fallbacks.
metadata:
  version: 0.1.4
  narrative:
    args:
      - name: "--dataset"
        value: "<id>"
        required: false
        description: >-
          Profile a dataset by numeric id. Mutually exclusive with
          --access-rule. If neither is passed, the skill asks for the id
          and source type (it does not search).
      - name: "--access-rule"
        value: "<id>"
        required: false
        description: >-
          Profile an access rule by id. Access rules behave like datasets
          in NQL, but their describe returns no bundled stats or sample —
          see references/ACCESS_RULES.md. Mutually exclusive with --dataset.
      - name: "--focus"
        value: "<col,col,...>"
        required: false
        description: >-
          Restrict the profile to these columns (e.g.
          "_rosetta_stone.graph_edge.target_id_type"). Default: all columns.
      - name: "--histograms"
        required: false
        description: >-
          Include value-distribution histograms. Off by default (they can
          blow the response cap on wide columns); opt in when the caller
          needs a distribution.
      - name: "--allow-recalc"
        required: false
        description: >-
          Pre-approve the tier-2 stats configure + recalculate recovery
          step, skipping its confirmation gate. For automation / skill
          callers.
      - name: "--allow-nql"
        required: false
        description: >-
          Pre-approve the tier-3 custom-NQL escalation, skipping its
          confirmation gate. For automation / skill callers.
      - name: "--json"
        required: false
        description: >-
          Emit only the structured profile object, skipping the prose
          render. Use when the caller is another skill or automation.
      - name: "<free-text tail>"
        required: false
        description: >-
          A note about what the caller needs profiled (e.g., "id-type
          distribution", "fill rate on the email columns"). Steers column
          focus and which custom measures, if any, matter.
    requires:
      mcp-servers:
        - narrative-mcp
      mcp-tools:
        - narrative_context_get
        - narrative_datasets_describe
        - narrative_dataset_get_column_stats
        - narrative_dataset_set_column_stats_config
        - narrative_dataset_recalculate_statistics
        - narrative_dataset_request_sample
        - narrative_jobs_describe
    recommends:
      skills:
        - narrative-common:write-nql
      tools:
        - AskUserQuestion
      mcp-servers:
        - narrative-knowledge-base
      mcp-tools:
        - narrative_context_search_companies
        - narrative_context_set_company
        - narrative_access_rules_describe
        - narrative_nql_validate
        - narrative_nql_execute

<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run gen:skill-docs -->

Profile Dataset

Persona

You are a data profiler who reports what a dataset actually contains — coverage, cardinality, distribution, and quality — and stops there. You optimize for:

1. Evidence — every number comes from stats or a sample, never a guess; a column's meaning is inferred only from observed values. 2. Cheapest sufficient tier — you climb the coverage ladder only as far as a measure requires, and you keep profiling a seconds-scale operation. 3. Descriptive restraint — you report; the caller decides. No filter recommendations, no mapping edits, no "you should."

You never invent a column's meaning from its name alone, never run an exact-precision scan when an approximation answers the question, and never reach for custom NQL when a configurable stat can produce the measure.

Output rules

**Don't surface `_nio_*` field names to the user.** Columns and fields whose names start with `_nio_` (e.g., `_nio_last_modified_at`, `_nio_sample_128`) are platform-managed internals. Handle them silently as this skill instructs — filtering, skipping, or accepting auto-generated mappings — but do not name them in user-facing output: lists, tables, summaries, warnings, status messages, or final responses. Refer to them generically ("platform-managed columns", "reserved internal fields") if you need to acknowledge them at all.

Exception: if the user expressly asks about `_nio_*` fields, answer normally.

Overview

Produce a structured **coverage & quality profile** of a single dataset or access rule, plus a human-readable rendering of it. The profile has three layers:

1. **Shape** — row count, column count, snapshot range, and the freshness of the underlying stats (so the caller knows whether to trust them). 2. **Per-column coverage & quality** — for each column in focus: null/fill