Enhance AI analysis capabilities with structured workflows for disciplined insights.

Perlytics Skill

Teach AI to think like a disciplined analyst, not a clever chatbot.

Most AI-generated business analysis fails in the same predictable ways: it answers too early, assumes the metric, skips the baseline, mixes facts with speculation, and produces outputs that sound polished but are hard to act on.

perlytics-skill is an open-source, installable skill pack that fixes those habits. It gives AI a practical analyst workflow:

clarify the question before answering
define the metric before interpreting it
separate observation, inference, hypothesis, and recommendation
reason with dimension, grain, timeframe, baseline, and filters
acknowledge uncertainty and missing context
deliver decision-ready outputs

Before / After

User ask

Why did revenue drop last month?

Typical weak AI answer

Revenue may have dropped because of seasonality, lower conversion, weaker marketing performance, or customer churn.

With perlytics-skill

Clarified question: Are we analyzing gross or net revenue, billed or recognized revenue, and which market?

Working metric: net recognized revenue, daily grain, compared with the prior 4-week baseline.

Initial decomposition: traffic x conversion x average order value x cancellation/refund rate.

Output: observations, plausible drivers, confidence level, missing context, and next actions.

Who It Is For

business analysts
data analysts
BI analysts
product and growth analysts
founders and operators
consultants
PM, ops, and marketing teams using AI for analysis

Skills Included

Foundation

analysis-readout — default entry point for generic analysis tasks
clarify-question — forces precise question scoping before any analysis
metric-definition — establishes denominator, grain, and comparison baseline

Diagnostic

hypothesis-tree — structured decomposition of plausible drivers
root-cause-analysis — systematic diagnosis from symptom to root cause

Analysis modes

funnel-analysis
cohort-retention
experiment-readout
exploratory-data-analysis
forecasting-readout
segmentation-analysis
causal-inference-check

Data quality

data-quality-check

Review and communication

dashboard-critique
stakeholder-memo
data-request-spec

Browse the canonical source in skills/.

Installation

Claude Code (native plugin)

/plugin marketplace add thuong-nc/perlytics-skill
/plugin install perlytics-skill

After install, Claude Code automatically applies the right skill based on what you ask — no slash commands needed.

Other AI tools (Cursor, Copilot, Codex, ...)

Download the prebuilt bundle from Releases and copy the contents of generic-agent-folder/skills/ into your tool's skill directory.

Or clone and build locally:

git clone https://github.com/thuong-nc/perlytics-skill.git
cd perlytics-skill
python build.py
# outputs to dist/markdown/ and dist/generic-agent-folder/

Example Use Cases

Diagnose an ecommerce GMV drop with clarify-question, metric-definition, hypothesis-tree, and root-cause-analysis
Review a SaaS pricing test with metric-definition, experiment-readout, and stakeholder-memo
Improve a support operations dashboard with dashboard-critique and data-request-spec
Turn a vague retention question into a disciplined cohort readout with cohort-retention
Start a generic CSV or KPI readout with analysis-readout

See domain walkthroughs in examples/:

Pack Structure

.claude-plugin/   Claude Code plugin descriptor and marketplace
skills/           Canonical editable skill sources
settings.json     Auto-trigger map (injected as plugin custom instructions)
manifests/        Pack metadata
examples/         Example datasets and walkthroughs
dist/             Generated outputs for other AI tools
build.py          Developer build script

Generated outputs go to:

dist/markdown/
dist/generic-agent-folder/
dist/bundles/

Packaging Model

Each skill has two files:

SKILL.md — human-readable instructions, browsable on GitHub
skill.yaml — structured metadata used by validation, export, and installation

This keeps the repo easy to inspect while making it possible to export selected skills, build release bundles, and add future adapters without rewriting source skills.

See docs/packaging.md.

Building dist/ (for maintainers)

The dist/ outputs are generated — do not edit them directly.

python build.py          # build all targets
python build.py validate # validate skill sources only

Compatibility

Claude Code: native plugin via /plugin command (self-hosted marketplace)
Cursor, Copilot, Codex, Continue: install from dist/generic-agent-folder/ or dist/markdown/

See docs/compatibility.md.

Project Philosophy

This pack treats analysis like an operating system, not a style preference.

The core rules:

do not answer too early
do not assume metric definitions
separate observation from interpretation
use explicit analytical structure
acknowledge uncertainty
produce outputs someone can act on

Read docs/philosophy.md.

What This Repo Is Not

a random prompt dump
a vague productivity toolkit
a notebook of analyst thoughts
a theoretical analytics textbook
a fake marketplace plugin with undocumented compatibility claims

Contributing

Contributions are welcome, but the quality bar is deliberate.

Good contributions:

reusable analyst workflows
sharper business examples
stronger export adapters
cleaner packaging and validation

Weak contributions:

generic prompts
vague strategy templates
filler content
examples that sound smart but are not decision-ready

Start with docs/contribution-guide.md.

Roadmap

Current milestones live in ROADMAP.md.

Release Strategy

The pack uses Semantic Versioning:

MAJOR = breaking structure or compatibility changes
MINOR = new skills, export targets, or meaningful enhancements
PATCH = wording, metadata, and packaging fixes

Recommended release assets:

dist/bundles/perlytics-skill-<version>-markdown.zip
dist/bundles/perlytics-skill-<version>-generic-agent-folder.zip

License

Apache-2.0. See LICENSE.

Star History