archaeology
Skill304 starsChanged 2 months agoMITView on GitHub
Retrieve proven SQL patterns, table cheatsheets, and join patterns from .knowledge/query-archaeology/ so past work gets reused. Fire as a pre-flight step before writing ANY SQL. Also trigger on "do we have a known query for X", "how do we usually join these tables", "have we computed this metric before". If the store is empty or missing, exit silently. Also owns the writer convention: after a validated analysis, curate the final SQL here.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- Khan/perseustheir own version, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- Khan/perseus★ 1.6ksame name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository65 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- always-compareSkill
- analysis-designSkill
- analyst-coreSkill
- archive-analysisSkill
- auth-preflightSkill
- businessSkill
- causalSkill
- chart-to-driveSkill
- close-the-loopSkill
- codex-reviewSkill
- compare-datasetsSkill
- connect-dataSkill
- connect-snowflakeSkill
- context-compareSkill
- context-traceSkill
- data-inspectSkill
- data-mapSkill
- data-profilingSkill
- data-quality-checkSkill
- datasetsSkill
- distribution-profilerSkill
- evalSkill
- evaluate-graderSkill
- experiment-briefSkill
- experimentSkill
- exploreSkill
- exportSkill
- forecastSkill
- google-doc-exportSkill
- google-slides-exportSkill
- guardrailsSkill
- historySkill
- improve-contextSkill
- knowledge-bootstrapSkill
- log-correctionSkill
- maintain-contextSkill
- metric-specSkill
- metricsSkill
- monitor-evalsSkill
- notion-exportSkill
- paceSkill
- patternsSkill
- question-framingSkill
- question-routerSkill
- reliabilitySkill
- resume-pipelineSkill
- run-pipelineSkill
- runsSkill
- score-analysisSkill
- session-handoffSkill
- setup-dev-contextSkill
- setup-notionSkill
- setupSkill
- setup-slackSkill
- setup-snowflakeSkill
- srm-checkSkill
- stakeholder-communicationSkill
- stress-testSkill
- switch-datasetSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Automatically: before any analysis agent writes SQL (pre-flight step)
- Distinctive: line 22
Manually: when the user asks about known patterns for a table or join
- Very specific: line 29
Read .knowledge/query-archaeology/curated/index.yaml.
- Distinctive: line 43
Search each store that has entries (per index counts).
- Very specific: line 63
If only one search table, match if tables contains it as substring.
- Very specific: line 123
Create curated/index.yaml if it is missing (counters cookbook_entries, table_cheatsheets, join_patterns, all starting at 0), then increment …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill: Query Archaeology
Purpose
Retrieve proven SQL patterns, table cheatsheets, and join patterns from the query archaeology store so agents reuse validated work instead of writing SQL from scratch. The skill also defines the store's local write path: after a validated analysis, the final SQL is curated back into the store (the Writer Convention below), which is what makes the retrieval loop close.
When to Use
- Automatically before any analysis agent writes SQL (pre-flight step)
- Manually when the user asks about known patterns for a table or join
- After a validated analysis, to curate the proven SQL (Writer Convention)
Instructions
Step 1: Check the Index
Read .knowledge/query-archaeology/curated/index.yaml. Parse counters:
cookbook_entries, table_cheatsheets, join_patterns.
If all three are zero (or the file is missing), stop here. Return nothing and do not mention archaeology to the user.
Step 2: Identify Search Terms
From the current analysis context, extract:
- Table names the agent is about to query (e.g.,
orders,events) - Query intent tags (e.g.,
funnel,retention,revenue,cohort)
Step 3: Search the Three Stores
Search each store that has entries (per index counts). Match using
case-insensitive substring -- order matches orders, order_items.
3a. Cookbook (curated/cookbook/*.yaml)
For each file, check:
tablesarray -- any element contains a search table name as substring?tagsarray -- any element matches a query intent tag?
Extract on match: title, sql, tables, tags, and any caveats/notes.
3b. Table Cheatsheets (curated/tables/*.yaml)
For each file, check:
table_namecontains a search table name as substring?
Extract on match: table_name, grain, primary_key, common_filters,
gotchas, common_joins.
3c. Join Patterns (curated/joins/*.yaml)
For each file, check:
tablesarray -- at least two elements match search table names?- If only one search table, match if
tablescontains it as substring.
Extract on match: tables, join_sql, cardinality, notes, validated.
Step 4: Format Results
Return matched entries as a fenced context block. Omit sections with no matches.
--- QUERY ARCHAEOLOGY CONTEXT ---
## Cookbook Patterns
### {title}
Tables: {tables} | Tags: {tags}
```sql
{sql}Caveats: {caveats or "none"}
Table Cheatsheets
{table_name}
- Grain: {grain}
- Primary key: {primary_key}
- Common filters: {common_filters}
- Gotchas: {gotchas}
- Common joins: {common_joins summary}
Join Patterns
{tables[0]} <-> {tables[1]}
Cardinality: {cardinality} | Validated: {validated}
{join_sql}Notes: {notes}
--- END ARCHAEOLOGY CONTEXT ---
### Step 5: Agent Handoff
Pass the formatted block as additional context to the analysis agent. The
agent should prefer archaeology SQL over writing from scratch, respect any
gotchas listed, and note in working files when an archaeology pattern was used.
## Writer Convention: Curate After a Validated Analysis
Retrieval only pays off if something writes. After an analysis is validated
(the triangulation checks pass and the finding ships), curate the final proven
SQL into the store:
1. Allocate the next entry id `CK-{NNN}`: scan
`.knowledge/query-archaeology/curated/cookbook/` for the highest existing
number and increment (start at `CK-001` for an empty store).
2. Write `.knowledge/query-archaeology/curated/cookbook/{entry_id}.yaml` with:
`id`, `title` (what the query answers), `description`, `sql` (the final
validated SQL), `dataset`, `tables`, `tags` (query intent tags such as
`funnel`, `retention`, `revenue`), `source_analysis` (the analysis brief or
`.knowledge/analyses/` run-record filename), `created_at` and `last_used`
(today), `use_count: 0`. This is the same cookbook format the curated store
writes, so imported and locally curated entries live side by side.
3. Create `curated/index.yaml` if it is missing (counters `cookbook_entries`,
`table_cheatsheets`, `join_patterns`, all starting at 0), then increment
`cookbook_entries`.
Curate one entry per validated headline query, not every intermediate query.
Skip exploratory SQL and one-off sanity checks.
## Anti-Patterns
1. **Never mention archaeology when the store is empty** -- silent skip
2. **Never require exact matches** -- always substring so `order` finds `orders`
3. **Never load all files eagerly** -- check index counts first, skip zero stores
4. **Retrieval never modifies archaeology files** -- the pre-flight path is
read-only; only the Writer Convention appends entries, and only after
validation
5. **Never block analysis if retrieval fails** -- archaeology is additive, not a gateDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

