---
name: writing-analytical-skills
description: Use this skill when authoring a new skill for the analytics-skills framework, modifying an existing one, or adding domain-specific extensions (vertical packs like e-commerce-analytics, healthcare-analytics, or fintech-analytics). Provides conventions for SKILL.md authoring, integration with the methodology DB, handoff patterns between skills, and the principle of one-skill-one-gate. Trigger on phrases like "add a skill", "extend the framework", "write a new skill", "improve the [skill-name] skill", or any meta-work on the framework itself.
---

# Writing Analytical Skills

The framework grows by accumulating domain-specific and methodology-specific skills. This skill explains how.

## Principles

### One skill, one gate

Each skill enforces exactly one methodological commitment. Don't bundle. If a new commitment is being added, it gets its own skill. The framework's value is that each gate is hard to skip — bundled skills become soft gates.

### Skills hand off explicitly

Every skill ends by naming the next skill in the flow. No skill leaves the user wondering what happens next.

### Skills log to the methodology DB

Any skill that produces a meaningful artifact (prediction, decision, reconciliation, confound, fragility flag) writes to the methodology DB. The DB is the system's memory; skills that don't write to it can't contribute to the learning loop.

### Skills name their failure mode

A skill exists because some failure mode happens often enough to need an enforcement gate. Every SKILL.md should name that failure mode in its first paragraph. If you can't name the failure mode, the skill probably doesn't need to exist.

## SKILL.md conventions

```markdown
---
name: skill-name-in-kebab-case
description: When to trigger this skill (be explicit and pushy — Claude undertriggers). What it does. Required for [stakes level]. Trigger on phrases like [...].
---

# Skill Name

One-sentence statement of the failure mode this skill addresses.

## What this skill enforces

The procedural gates, in order. What must be done before the skill is satisfied.

## Logging

What gets written to the methodology DB.

## Boundary cases

When the skill applies marginally; when it doesn't apply; how to handle user pushback.

## Handoff

Which skill comes next.
```

## Vertical packs

Domain-specific extensions (healthcare, e-commerce, fintech, SaaS) live in their own plugins that *depend on* `analytics-skills` rather than fork it. A vertical pack adds:

- Domain confound libraries (seed entries for `confound_library`)
- Domain source-of-truth registries (entries for `source_of_truth`)
- Domain-specific skills (e.g., `clv-cohort-stitching` for e-commerce, `settlement-reconciliation` for fintech, or `payer-mix-decomposition` for healthcare)
- Reference SQL patterns

The methodology layer stays shared; the domain knowledge layer accumulates.

## Eval and iteration

Skills are not write-once. After deploying a skill, watch where it under-triggers (didn't activate when it should have) or over-triggers (activated noisily). Refine the description first — the description is the primary triggering mechanism. Refine the body second.

For evaluation infrastructure, the [skill-creator skill](https://github.com/anthropics/skills) provides scripts for benchmarking trigger rates and quality. Use it.