artifact-management - SKILL.md Agent Skill

name: artifact-management description: Save, organize, and describe reusable analysis artifacts such as SQL, result snapshots, CSV exports, summaries, caveats, plots, and report-ready files. Use when users ask to save, export, share, cite, reproduce, or organize data-analysis outputs.

Artifact Management

Use this skill when analysis outputs should persist beyond the current conversation.

When to store artifacts

Store analysis artifacts when:

the user asks to save, export, share, cite, or reproduce an analysis
a chart, report asset, or presentation-ready output is generated
the analysis may be reused for a decision, review, dashboard follow-up, or external-facing answer
the query result is non-trivial and the SQL, assumptions, or caveats matter for interpretation

Do not write files into a repository or long-lived location unless the user requested persistence or approved the destination.

What to store

Prefer storing enough context for someone to reproduce and critique the analysis later:

original user question or decision context
metric definitions, assumptions, population, grain, time window, filters, and exclusions
source models/tables and relevant data-dictionary references
final SQL or query source
result snapshot, such as CSV, JSON, Parquet, or a small markdown table
narrative summary, findings, evidence, confidence, and caveats
generated plot files and the underlying data used to create them
reproduction instructions, including commands or tool steps when helpful
creation timestamp and author/tool context when useful

Recommended local structure

Use a dated, human-readable slug for each analysis package:

analyses/
└── 2026-05-27-active-users-trend/
    ├── README.md
    ├── query.sql
    ├── result.csv
    ├── summary.md
    ├── chart.html
    ├── chart.png
    └── metadata.json

For lightweight exports, a single CSV or markdown file is fine. For reusable or report-ready work, prefer the package structure above.

Reproducible generated artifacts

When an artifact is generated by code, preserve enough context to reproduce and safely modify it later:

Save the generator script or notebook alongside the generated outputs when practical.
Keep generated files reproducible from the saved script and source data.
If fixing a generated artifact, update the generator and regenerate the output. Avoid only hand-patching generated files, because that causes drift between the source script and artifact.
If a generated file must be manually patched, document that in README.md, summary.md, or metadata.json and state whether the generator is stale.
Save validation steps that were performed, such as SQL row counts, JavaScript syntax checks, local render checks, or browser viewing notes.

For interactive HTML artifacts, include viewing instructions when browser security context may matter. For example:

cd path/to/artifact-directory
python3 -m http.server 8000

Then open http://localhost:8000/chart.html instead of relying on file:// behavior.

If a lightweight chart evolves into a reusable or report-ready asset, upgrade the artifact package with a human-readable README.md that includes:

question and short answer
metric definition and definition provenance
source model/table and SQL/query notes
time window, grain, filters, and exclusions
artifact inventory
caveats and sensitivity notes
validation performed
reproduce/refresh instructions

README template

# Analysis title

Question: ...

Answer: ...

How I measured it:
- Metric: ...
- Population: ...
- Grain/window: ...
- Filters/exclusions: ...
- Source model/table: ...

Artifacts:
- `query.sql` — final query
- `result.csv` — result snapshot
- `summary.md` — findings and caveats
- `chart.html` / `chart.png` — visualization, if generated

Caveats:
- ...

Reproduce:
1. ...

Metadata fields

When creating metadata.json, include fields like:

{
  "title": "Active users trend",
  "created_at": "2026-05-27T15:40:00-07:00",
  "question": "...",
  "time_window": "...",
  "grain": "...",
  "models": ["..."],
  "metrics": ["..."],
  "filters": ["..."],
  "caveats": ["..."],
  "artifacts": ["query.sql", "result.csv", "summary.md", "chart.html"]
}

Safety and privacy

Avoid persisting sensitive raw rows unless they are necessary and explicitly requested.
Prefer aggregate, sampled, redacted, or anonymized outputs for shareable artifacts.
Make caveats visible next to exported numbers and charts.
Do not publish or upload artifacts to external services unless the user explicitly asks.
If storing in a shared repository, avoid secrets, credentials, private customer data, and overly broad raw exports.

Output reporting

After saving artifacts, report:

absolute or workspace-relative paths
what each artifact contains
any sensitivity caveats
how to reproduce or refresh the analysis

Boundaries

This skill does not replace a BI tool, governed dashboards, documented metric definitions, or a source-of-truth reporting system. Treat persisted artifacts as snapshots unless they are backed by documented models and an agreed refresh process.