convez.ai
Skill
samwedll

analytics-skills

samwedll/analytics-skills

Ver no GitHub
InicialPluginScore · de 0 a 100

An agentic skills framework for analytical work — methodology that keeps numbers rooted in truth. A Claude Code plugin: twelve composable skills enforcing analytical rigor.

Instalação

$npx convez-ai samwedll/analytics-skills

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

analytics-skills

An agentic skills framework for analytical work. Methodology that keeps numbers rooted in truth.

A Claude Code plugin marketplace built in the spirit of Superpowers — but where Superpowers enforces software-development discipline (TDD, root-cause debugging, evidence over claims), analytics-skills enforces the analytical-work equivalents: framing the question, predicting before querying, reconciling to source, auditing confounds, walking the multiverse of analytical paths, and ensuring every number has a receipt.

Why this exists

Analysis without methodology is storytelling. The story can be true or false; without methodology, you don't know which. LLMs make this worse: they emit plausible-sounding numbers fast, with clean narratives, and rarely log the choices they made along the way.

This framework exists to enforce the gates that humans skip and LLMs skip even more enthusiastically.

The methodology shape

framing → discovery → planning → predict-then-query → execution
                                                          ↓
                              reconciling-to-source ← (when authoritative source exists)
                                                          ↓
                                          confound-audit + multiverse-analysis
                                                          ↓
                                                sensitivity-analysis
                                                          ↓
                                          analytical-self-review
                                                          ↓
                                                evidence-over-claims
                                                          ↓
                                                       writeup

Each arrow is a gate. You don't skip ahead. You don't parade ad-hoc work as rigorous.

The twelve skills

SkillRole
getting-startedBootstrap orchestrator
framing-the-questionRefuses to query until the question is operationalized, decision-anchored, falsifiable, and stakes-flagged
data-discoverySchema, grain, freshness, provenance, hygiene before any plan
analytical-planningPopulation, window, metric, segments, validation queries, confound list — written before SQL
predict-then-queryKeystone. Written prediction with reasoning before the headline query runs
reconciling-to-sourceNew query must tie out to authoritative source when one exists
confound-auditWalk the confound checklist; rule each in or out with evidence
multiverse-analysisLog every analyst choice; run plausible alternatives; flag fragile results
sensitivity-analysisIdentify which parameters move the answer enough to change the decision
analytical-self-reviewSimpson's, base-rate, leakage, falsification, drift check
evidence-over-claimsEvery number traces to a re-runnable artifact
writing-analytical-skillsMeta-skill for authoring new skills and vertical packs

Installation

# In Claude Code:
/plugin marketplace add samwedll/analytics-skills
/plugin install analytics-skills@analytics-skills

Then start any analytical conversation. The getting-started skill bootstraps automatically and routes you through the methodology.

Updating after editing skills locally

The Skill tool reads from the install cache, not your source repo. If you edit skill files in this repo and start a new Claude Code session, the running session will keep loading the previously installed version until you refresh:

/plugin update analytics-skills
/reload-plugins

/plugin install is not enough on its own — if it reports "already installed", nothing has been refreshed. You need update then reload.

To verify which version is actually loaded, check ~/.claude/plugins/installed_plugins.json. The installPath field for analytics-skills is the directory the Skill tool is reading from; compare it against marketplace.json's version to confirm.

The install cache at ~/.claude/plugins/cache/analytics-skills/analytics-skills/ accumulates one subdirectory per version installed over time (0.1.0/, 0.2.0/, 0.3.0/, …). The bootstrap in getting-started picks the highest version automatically, so stale cache dirs are harmless — but you can delete old version subdirs by hand if you want a clean slate.

The methodology DB

A local SQLite database at .analytics/methodology.db (created on first use, see plugins/analytics-skills/scripts/db.py) turns the framework from a checklist into a learning system. It logs:

  • Predictions — every predict-then-query call with predicted value, range, reasoning, confidence, actual, delta, and in-range flag. Builds an analyst calibration curve over time.
  • Path decisions — every analyst choice with rationale, alternatives, and pre-specified vs. post-hoc tag. Forensic record of how the analysis was constructed.
  • Skill activations — which skills triggered when. Used to evaluate the methodology itself.
  • Confound library — domain-specific confounds learned and codified over time. Becomes proprietary IP.
  • Source-of-truth registry — known authoritative numbers for automatic reconciliation.
  • Reconciliations — every reconcile-to-source check with deltas.

After enough resolved predictions, calibration_summary() produces hit-rate-by-confidence-bin so an analyst can see whether their stated confidence is calibrated to actual outcomes.

Vertical packs

The methodology layer is domain-agnostic. Domain-specific knowledge lives in vertical packs — separate plugins that depend on analytics-skills and add domain confounds, source-of-truth registries, and domain skills. Planned packs:

  • fintech-analytics — ledger and settlement schema, regulatory-reporting source-of-truth registries, domain confounds (promo-credit inflation, chargeback timing, settlement-vs-ledger reconciliation), and skills like settlement-reconciliation
  • More TBD as the framework matures

Status

v0.5 — same twelve skills, now closing the missing-adjacent-context gap surfaced by the post-v0.4 dogfood. An analyst (or LLM session) framing a new question can be unaware that a sibling question — sitting in the same .analytics/questions/ directory — already documents an intervention that will explain the new question's results. When that happens, predict-then-query predictions go OUT_OF_RANGE for a reason the framework could have known about up front. v0.5 adds two gates that close this loop:

  • framing-the-question acquires an Adjacent context check section. After the four tests, the analyst must run a new adjacent-questions CLI command, review each surfaced sibling question, and either incorporate its findings as confounds or log a context-check-dismissed path-decision. Empty results also require a path-decision — the audit trail records the check itself, not just non-empty findings.
  • predict-then-query acquires a corrective context check in its OUT_OF_RANGE branch. Before drilling into query-bug-vs-model-update, the skill re-runs the adjacency CLI and asks the user three concrete questions (active intervention? parallel analysis? pipeline change?), logging an out-of-range-context-check path-decision regardless of whether new context surfaces.
  • db.py acquires the adjacent-questions CLI command. Scoring combines slug-token overlap (weight 3.0), decision-keyword overlap (2.0), in-flight status (1.5), and recency (1.0). Pure stdlib; tested via test_db.py.

Defense in depth: the preventive check at framing catches filesystem-discoverable context; the corrective check at OUT_OF_RANGE catches everything else.

Earlier v0.4 release notes (still in effect):

  • Bootstrap picks the highest-version cached db.py; README documents /plugin update + /reload-plugins refresh ritual.
  • framing-the-question working-assumption protocol, pre-aggregated source handling, and Revisions-log re-framing procedure.
  • data-discovery sample-metric sanity check, "what NOT to look at" guard, and back-edge handoff to framing.

Domain-generic still; domain knowledge still belongs in vertical packs.

Credit

Methodology shape modeled on Jesse Vincent's Superpowers. The "skills as enforcement gates" pattern is theirs; this framework ports that pattern from software development to analytical work. The garden-of-forking-paths framing comes from Andrew Gelman.

License

MIT.

Ver o original no GitHub

Bom para

Relacionados