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.
1---2name: artifact-management3description: 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.4---5
6# Artifact Management
7
8Use this skill when analysis outputs should persist beyond the current conversation.
9
10## When to store artifacts
11
12Store analysis artifacts when:
13
14- the user asks to save, export, share, cite, or reproduce an analysis
15- a chart, report asset, or presentation-ready output is generated
16- the analysis may be reused for a decision, review, dashboard follow-up, or external-facing answer
17- the query result is non-trivial and the SQL, assumptions, or caveats matter for interpretation
18
19Do not write files into a repository or long-lived location unless the user requested persistence or approved the destination.
20
21## What to store
22
23Prefer storing enough context for someone to reproduce and critique the analysis later:
24
25- original user question or decision context
26- metric definitions, assumptions, population, grain, time window, filters, and exclusions
27- source models/tables and relevant data-dictionary references
28- final SQL or query source
29- result snapshot, such as CSV, JSON, Parquet, or a small markdown table
30- narrative summary, findings, evidence, confidence, and caveats
31- generated plot files and the underlying data used to create them
32- reproduction instructions, including commands or tool steps when helpful
33- creation timestamp and author/tool context when useful
34
35## Recommended local structure
36
37Use a dated, human-readable slug for each analysis package:
38
39```text
40analyses/
41└── 2026-05-27-active-users-trend/
42 ├── README.md
43 ├── query.sql
44 ├── result.csv
45 ├── summary.md
46 ├── chart.html
47 ├── chart.png
48 └── metadata.json
49```
50
51For lightweight exports, a single CSV or markdown file is fine. For reusable or report-ready work, prefer the package structure above.
52
53## Reproducible generated artifacts
54
55When an artifact is generated by code, preserve enough context to reproduce and safely modify it later:
56
57- Save the generator script or notebook alongside the generated outputs when practical.
58- Keep generated files reproducible from the saved script and source data.
59- 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.
60- 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.
61- Save validation steps that were performed, such as SQL row counts, JavaScript syntax checks, local render checks, or browser viewing notes.
62
63For interactive HTML artifacts, include viewing instructions when browser security context may matter. For example:
64
65```bash
66cd path/to/artifact-directory
67python3 -m http.server 8000
68```
69
70Then open `http://localhost:8000/chart.html` instead of relying on `file://` behavior.
71
72If a lightweight chart evolves into a reusable or report-ready asset, upgrade the artifact package with a human-readable `README.md` that includes:
73
74- question and short answer
75- metric definition and definition provenance
76- source model/table and SQL/query notes
77- time window, grain, filters, and exclusions
78- artifact inventory
79- caveats and sensitivity notes
80- validation performed
81- reproduce/refresh instructions
82
83## README template
84
85```md
86# Analysis title
87
88Question: ...
89
90Answer: ...
91
92How I measured it:
93- Metric: ...
94- Population: ...
95- Grain/window: ...
96- Filters/exclusions: ...
97- Source model/table: ...
98
99Artifacts:
100- `query.sql` — final query
101- `result.csv` — result snapshot
102- `summary.md` — findings and caveats
103- `chart.html` / `chart.png` — visualization, if generated
104
105Caveats:
106- ...
107
108Reproduce:
1091. ...
110```
111
112## Metadata fields
113
114When creating `metadata.json`, include fields like:
115
116```json
117{
118 "title": "Active users trend",
119 "created_at": "2026-05-27T15:40:00-07:00",
120 "question": "...",
121 "time_window": "...",
122 "grain": "...",
123 "models": ["..."],
124 "metrics": ["..."],
125 "filters": ["..."],
126 "caveats": ["..."],
127 "artifacts": ["query.sql", "result.csv", "summary.md", "chart.html"]
128}
129```
130
131## Safety and privacy
132
133- Avoid persisting sensitive raw rows unless they are necessary and explicitly requested.
134- Prefer aggregate, sampled, redacted, or anonymized outputs for shareable artifacts.
135- Make caveats visible next to exported numbers and charts.
136- Do not publish or upload artifacts to external services unless the user explicitly asks.
137- If storing in a shared repository, avoid secrets, credentials, private customer data, and overly broad raw exports.
138
139## Output reporting
140
141After saving artifacts, report:
142
143- absolute or workspace-relative paths
144- what each artifact contains
145- any sensitivity caveats
146- how to reproduce or refresh the analysis
147
148## Boundaries
149
150This 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.
cline