Skip to content

Skills & packaging

In short

  • 17 skills: seven parleml-* analyst skills for reading results, and ten ml-* skills that deliver, investigate and operate models.
  • Install them in any host that reads skill files: Claude Code, Cursor, Codex or Gemini CLI. They teach the agent the workflow; the MCP tools do the work.
  • The ten ml-* skills are also the parleml-ml-lifecycle pack that ParleML's own agent sessions run.
  • scripts/build_skill_bundles.py --dist DIR builds one pack for every host from one source.

Seventeen skills are the MCP's onboarding + discovery layer: installed in a host that reads skill files (Claude Code, Cursor, Codex, Gemini CLI), a skill auto-triggers on a relevant question and primes the agent with the parleml workflow — then the agent uses the MCP tools. The pack ships no runtime client; it teaches, the MCP does.

Skill What it covers
parleml-explore Entry point — connect, decision ladder, catalog, SQL, AutoDoc
parleml-supervised Predictions star schema, rules/archetype joins, evaluation reads
parleml-unsupervised Clustering / anomaly schema and segment questions
parleml-forecast Forecast schema, (series, ts) joins, forecast charts
parleml-ranking-reco Recommendation / LTR schema and item joins
parleml-association Market-basket schema, rule↔item bridge, holdings, audiences
parleml-explain Evaluation, insights, per-row cases, driver charts
ml-delivery Builder token — frame, shape the data, baseline, iterate, challenge, decide, release — for every experiment type
ml-investigate Answer a question about data, an experiment or a model, "what if" included; writes an investigation report, changes nothing
ml-operate Check a model for drift (compare(kind="datasets")) and propose a retrain
ml-frame … ml-release The steps ml-delivery runs: ml-frame, ml-data, ml-baseline, ml-iterate, ml-challenge, ml-decide, ml-release

The ten ml-* skills are also the parleml-ml-lifecycle pack that ParleML's own agent sessions run (installed into <data_root>/config/packs/ by the backend, and replaced at boot whenever the packaged skills or references change; the standard profile selects it). Their frontmatter carries the runtime's parleml-* metadata (stage, orchestration mode, template chain, model tier, max turns, scope); a host that does not know those keys ignores them. They name no agent vendor, and each root says what to do when the session tools (ask_gate, run_skills) are missing: ask in chat, recommended option first.

The lifecycle is written once for every experiment type. ml-frame proposes the type and the person confirms it at the framing gate; every later step then follows that type's playbook (get_playbook("type-…"), bundled as references/type-*.md), which answers each step under the same headings — frame, data, validation, baseline, iterate, insights, challenge, decide, release:

Experiment Playbook Operating point (Decide)
binary, multiclass, regression type-supervised threshold (business_value), cost matrix (multiclass_cost), interval level
forecast type-forecast horizon and interval level
anomaly, clustering type-unsupervised alert budget (unsupervised_threshold); the segmentation
recommendation, learning-to-rank type-recommendation ranking tilt (ranking_at), per-product cost lens
association rules type-association the rule shortlist and its cut-offs
text in any of them type-text the base type's

Each playbook's baseline plan is tested end to end: it plans and launches through the MCP on the sample dataset it names, and every setting a playbook names by its path is checked against the plan schema. The parleml-* analyst packs stay the read path over published results and point at the playbooks for the computed reads.

The steps are written for agents that iterate like scientists and use the whole platform:

  • The interpretation sweep. Each playbook's Insights is an ordered list of reads — for a supervised run the rules that hold up on Test, archetypes, the error tree, engineered features, ALE, the surrogate, label noise, fairness, text terms and the glass box. ml-iterate runs it on the baseline and every winner and keeps a short Gems table; the candidate is explained at deep before the challenge, whose report names the reads each check required.
  • The five checks (playbook/iterate.md): a run is spent only on an idea with a mechanism, evidence, an expected effect that could be refuted, nothing ParleML already does, and a business reason; the floor first, a gain inside the parent's CI is no evidence, and the next run starts from the best evidenced one.
  • Business domains are mapped on every string column, with the companion columns that unlock distance and match features (playbook/type-supervised.md, Business domains).
  • Releases are data: the release record carries the operating point and the surface that applies it, the challenge's conditions with the person's answers and the limitations.

Every rendered SKILL.md directs the agent to the parleml MCP tools (connector setup in parleml-explore) and opens with the same line: defer to the MCP; never re-implement what the tools compute. The pack is guidance, not a parallel runtime. Custom attributes live under metadata as strings (Skill attributes) — ml-delivery declares parleml-orchestration-mode: guided, its parleml-template-chain (the steps and the person's gates between them) and parleml-scope: builder.

One SSOT, generated bundles

Authored bodies live in the parleml-mcp package (parleml_mcp/parleml_mcp/skills/ + reference/); scripts/build_skill_bundles.py renders each pack self-contained (its own references/), byte-checked against the source by test_skill_bundles.py. A bundle carries no client — the agent uses the MCP. Never hand-edit a rendered copy.

uv run python scripts/build_skill_bundles.py            # render .cursor/skills
uv run python scripts/build_skill_bundles.py --check    # verify .cursor/skills is in sync
uv run python scripts/build_skill_bundles.py --dist DIR # publishable tree
uv run python scripts/build_skill_bundles.py --runtime-pack DIR # the parleml-ml-lifecycle pack

The pack (--dist)

--dist DIR produces one pack for every host — the same name (parleml) and version (the parleml-mcp package's) in every manifest:

File For What it does
skills/<skill>/ every host the self-contained skills (each with its own references/)
apm.yml APM (Agent Package Manager) apm pack → a target-neutral bundle; apm install <bundle> --target claude \| cursor \| … installs it
.claude-plugin/plugin.json, marketplace.json, .mcp.json Claude Code a plugin that installs the skills and connects the parleml MCP server
.cursor-plugin/plugin.json, cursor/mcp.json Cursor the plugin, and the server entry for .cursor/mcp.json (${env:…} references)
gemini-extension.json, GEMINI.md Gemini CLI an extension: the server entry and the host instructions
.codex-plugin/plugin.json Codex a plugin (Codex's plugin manifest) with the skills; it names no server — Codex sends ${…} as literal text, so the server comes from codex/config.toml
AGENTS.md, codex/config.toml Codex the host instructions and the [mcp_servers.parleml] entry (the HTTP url, with bearer_token_env_var)

The server entries read PARLEML_MCP_URL (your parleml /mcp URL) and PARLEML_API_TOKEN (a token from Settings → Access) from the environment, in each host's own syntax — the pack never contains a secret, and no config file ever holds the token. Web hosts sign in with OAuth instead (see Connect your agent).

Next