Skip to content

Skill attributes

In short

  • A skill is an Agent Skills folder with one SKILL.md. Optional metadata.parleml-* keys tell ParleML how to show and run it.
  • The keys set the skill's summary, stage, model tier, turn cap and token scope, and whether people can start it as a session.
  • Every metadata value is a string: quote numbers.
  • Edit skills in Settings → Skill packs. A shipped skill saves as Your version and can be reset at any time.

Every skill is an Agent Skills folder with one SKILL.md. The standard frontmatter identifies the skill; optional metadata.parleml-* strings tell the runtime how to present and run it.

---
name: ml-baseline            # the skill id: equals its folder name, kebab-case
description: >-              # when an agent should choose this skill (required)
  Run the first ParleML experiment on an approved training table …
metadata:
  parleml-summary: 'Runs the first experiment on the approved table and records the score every later model must beat.'
  parleml-stage: model
  parleml-model-tier: fast
  parleml-max-turns: '60'
  parleml-scope: builder
---

# Baseline                   ← the first H1 is the skill's title
  • name must equal the folder name; description must not be empty.
  • Every metadata value is a string. Quote numbers: parleml-max-turns: "60". An unquoted number or true is refused, naming the key.
  • Unknown metadata keys are kept and ignored.
  • You can write the frontmatter by hand, or use the skill editor in Settings → Skill packs (below).

The keys

Key Applies to Values Meaning
parleml-summary any one line, at most 160 characters What people read where the skill is offered (the ✦ Agent menu, the start screen) and while it works (the flow map, the run view's skill_summary). description stays the model's routing text: when to use the skill and when not to, which people never see. Absent, people see only the title; the skill editor and Validate warn.
parleml-stage steps a stage id from settings.yaml (default frame, data, model, decide, operate) Where the step sits on the stage strip. An id the catalog lacks degrades the strip, never the run. Orchestrators may also carry a high-level label; their preview may cover several stages.
parleml-orchestration-mode orchestrators guided or adaptive Makes the skill a possible session root. guided describes a process in the instructions; adaptive describes open-ended investigation. Both use the native agent and may have an optional preview. Absent means an ordinary step.
parleml-template-chain orchestrators a schematic (below) Optional inferred flow-map legend. Never an execution contract or a requirement to run.
parleml-model-tier any strong, default, fast How much model the skill needs. The profile's CLI maps it to a model (Configuring agents). A tier outranks the profile's plain model.
parleml-max-turns any a positive integer, quoted Turns allowed in one attempt of this skill. Outranks the profile and the server default (Limits).
parleml-scope any analyst, compute, builder The scope of the ParleML token each attempt of this skill gets: read-only, read plus compute probes, or building (bound to the session's workspace). Absent means analyst.

A skill is startable when its profile lists it in orchestrators and it declares parleml-orchestration-mode. Either alone is not enough; the start screen lists a broken root with its problem.

The optional flow preview

parleml-template-chain: 'ml-frame → gate:framing-approval → ml-data → gate:data-approval → ml-baseline → ml-iterate → ml-challenge → ml-decide → gate:release-approval → ml-release'
  • Phases are separated by the arrow →.
  • A skill phase is a skill id from the profile's packs.
  • gate:<id> marks a decision point (lowercase kebab-case).
  • [parallel] a + b is a parallel consultation of at least two skills. Parallel steps must be read-only: steps that write share one work directory and run one at a time.
  • No gates or nested groups inside a parallel group; no skill twice; at most 256 phases and 16 KiB.

The assistant derives this schematic from the instructions for visualization. It is not a plan the runtime enforces. Refresh it after changing the instructions; an incomplete preview does not block saving or execution. Decisions, order, and conditions belong in the skill instructions. The session records what actually ran.

Editing skills and packs

Settings → Skill packs edits packs in the configuration folder (administrators only). Every skill opens in the structured editor, including shipped skills.

Which packs a skill is resolved against. A chain may name skills from other packs, so the pack and skill pages resolve a skill against the packs of the first profile that selects its pack, and say which profile that is. With no such profile, the pack is resolved alone and a cross-pack phase shows as unresolved.

The skill page

  • The back link returns to the session it was opened from.
  • The profiles selecting the pack, and the live sessions that can still run the skill (they keep the version they started with).
  • The model each CLI's built-in tier mapping runs for the skill's tier, and the skill's recent results (runs, outcomes, median time) from every session on the server.
  • The documentation templates its instructions name, each opening the template editor.
  • Shipped skills save as Your version under the same id. No profile changes are needed. ParleML keeps the complete skill folder in config/skill-overrides/<pack>/<skill>/skill/, separately from shipped packs. Reset to shipped removes your version; live sessions keep their snapshot.
  • When ParleML updates a skill you edited, Review changes compares both versions with the original base. Merge into draft uses Git's three-way merge; resolve all conflict markers before saving. Keep mine accepts the new shipped base without changing your instructions.
  • Duplicate creates a new id and copies the whole folder. With no own pack, it creates My skills. Add the new skill to a profile to run it.
  • Your versions apply to hosted sessions on this server. Own-agent APM installs and shipped-pack exports continue to use the shipped content.
  • An orchestrator's Flow preview is drawn, never printed as its raw a → gate:b → c text: the stages it covers (each card counts its steps; a definition has no progress, so no card reads Not started), then the flow map a session draws, with nothing observed: agent steps and your decisions in order, parallel steps fanned out, each card naming its stage. Selecting a step names it, shows its description and opens its skill; List gives the same phases as an ordered list.
  • The SKILL.md preview uses the page's width, and a table scrolls rather than squeezing its columns.

The skill editor

Every skill opens in the editor:

  • Identity. The id never changes. Title is the SKILL.md's first heading; Description is the description agents match requests against. The Summary (parleml-summary, at most 160 characters), the line people read, is the first attribute field.
  • Attributes, one control per key above: the stage (from settings.yaml's catalog), the model tier with what each CLI runs for it, max turns (empty inherits the profile, then the server default) and the access scope (unset is analyst).
  • Orchestration: Ordinary skill, Guided orchestrator or Adaptive orchestrator. Changing modes preserves stage labels and preview metadata. Process behavior and applicability belong in the skill instructions and description.
  • Derive flow preview interprets the current instructions with the assistant. Review the optional proposal before using it. It can be refreshed for either kind of orchestrator and never defines execution order.
  • Apply to SKILL.md draft has the server write the form into the source: only the keys the form changed, so a hand edit to any other key survives. The editor says when the form is ahead of the source, and when the source was edited by hand after the form read it (Apply then reads the form back from the source). Nothing is written until Save.
  • SKILL.md in a source editor with Preview.
  • Draft checks. A moment after each change the server checks the skill. Unresolved or incomplete schematic information is a warning, not a blocker.
  • Save waits for the check of the draft on screen and is refused while it has a blocking error, saying which. It sends the version it was opened from; a newer version on the server refuses the save (412), keeps your draft and offers Reload. Form changes not yet applied are applied first. Delete skill is refused (409, naming them) while a profile starts it or an unfinished session can still run it.
  • Flow preview: the flow of the draft on screen once it has been checked (the saved one until then).

Suggest attributes

Tick what the assistant may change, pick Fill only unset attributes or Reconsider the ticked attributes, and ask. It goes through ParleML's one AI gateway (ask()): one bounded, tool-free call per batch of skills at the default tier, on the agent of the profile the pack is resolved with, else the next agent ready on this server (a paused one is skipped), which the result names. PARLEML_AGENTS_AUTHORING_ADAPTER=fake answers without a model (tests). Only the stage, the orchestration mode and the flow preview can be proposed; tier, max turns and scope are always set by a person.

  • On a skill, a proposal is applied to the form as one unit; you then apply and save as usual.
  • An orchestrator also offers Derive flow preview, which asks for the chain alone. A proposed chain is shown step by step: the steps it adds are marked +, the ones it drops are listed.
  • A proposal belongs to the draft it was made for: any change to the draft clears it.
  • On a pack, Review skill attributes proposes for every skill in it; Apply and save writes one skill's proposal against the version it was proposed for, so a skill changed meanwhile is refused, not overwritten.

The pack page

  • Pack settings: name, description and version, saved with the pack's ETag into every manifest it carries (.claude-plugin/plugin.json, the Cursor and Codex plugins, the Gemini CLI extension gemini-extension.json, apm.yml) in one step; each is listed with the host that reads it. The Codex and Gemini manifests are the ones parleml_mcp.pack_manifests defines for the shipped bundles, written for every pack. Delete pack is refused while a profile selects the pack or a session uses it.
  • Validate pack checks the manifests (and says which packaging manifest is out of step with the pack's name, description and version), the templates, rules and hooks, and every skill as saved, the way the skill editor checks one: an orchestrator a profile names is checked against that profile's packs. Export with APM downloads the pack as <pack>-<version>.zip, one folder that is an APM package (apm.yml at its root, the manifests in step): unzip it and run apm install ./<pack>-<version> --target claude|cursor|codex|gemini for your own agent, or bring it into another installation with Import a pack. Both work on the shipped pack; neither writes anything.
  • Skills, each with its stage or orchestration mode and any problem found resolving it. New skill: the title proposes the id (lower-case words joined by hyphens, correctable until created); description, attributes and Suggest attributes as in the editor; Apply to SKILL.md draft builds and validates the source, then Create skill. ✦ Draft with the assistant writes the whole SKILL.md from the title, id and description in one bounded call (ask(), the default tier, the agent of the profile the pack is resolved with): the routing description, the summary, the stage or orchestration mode and an optional schematic and the Purpose, Inputs, Steps and Output sections. It is shown for review (its findings, its attributes, the rendered draft) and reaches the form only through Use this draft. With no agent to ask, the starter draft comes back with a warning. API tokens are refused on this and on Suggest attributes: both are a person's, in Settings.
  • Documentation templates: each with the skills that name it, and New template (<skill-id>/<path>, stored in that skill's assets/templates/). The template editor uses the owning skill’s folder version and save path, including shipped skill edits. Existing sessions keep their resource snapshots. Pack-root templates are unsupported.
  • Rules and Hooks per host, and the pack's whole file inventory (Host-native rules & hooks).

Skill packs also offers New pack (an empty pack with its manifests, inert until a profile selects it) and Import a pack.

The shipped skills

Every shipped skill states a parleml-summary.

Skill Mode / stage Tier Turns Scope
ml-delivery guided strong 300 builder
ml-investigate adaptive default 120 analyst
ml-operate adaptive default 80 compute
ml-frame frame strong 80 analyst
ml-data data default 120 builder
ml-baseline model fast 60 builder
ml-iterate model default 200 builder
ml-challenge model strong 80 compute
ml-decide decide default 60 compute
ml-release operate default 40 builder

The Skill files selector edits references and documentation templates alongside SKILL.md; Add file creates a text file. Save keeps the whole draft together.

Interpretation provenance

Details: flow-preview fingerprints and pack imports

Flow previews are approximate descriptions, never execution rules. Deriving a preview records parleml-preview-source, a fingerprint of the source instructions and description. Editing those instructions marks the preview as changed; a preview without a fingerprint is unverified. Refresh the interpretation to record its current source. Neither state blocks a session. Repetition and movement between stages are normal skill behavior.

Pack imports accept APM apm.yml with skills/, .apm/skills/, or a root SKILL.md, Claude .claude-plugin/plugin.json, Cursor .cursor-plugin/plugin.json, and root plugin.json identities with standard skills/<id>/SKILL.md folders. Preview and installation reject skill IDs that are already installed. There is no pack-order rule that silently shadows a skill.

Next