Creating skill packs

A skill pack is a folder of Markdown, JSON and YAML files that teaches Kadmo's agents one product or one craft. This page shows how a pack is laid out, how to name its parts, the order in which agents read it, how to write knowledge an agent can act on, and how to publish a change to your account's pack repository or make it in the app. For what packs are and where they come from, see Skill packs.

You rarely start from an empty folder. Skill Discovery writes most of a pack from your product and its repositories, and you review and improve what it wrote. The rules below are the same either way.

Pack layout

Your account's pack repository holds one folder per domain, plus a few files at its root:

index.json                  every pack in the repository, with its version
_skill.md                   an overview of the whole repository
_roles/
  se.md                     account-wide role guides, one per role
  qa.md
_souls/
  se.md                     personas: the voice a role takes in chat
  qa.md
app.example.com/            one domain: a host, or a knowledge area such as billing-rules
  skill-pack.json           the domain's manifest
  _skill.md                 the domain root: what the product is, sign-in, navigation
  _roles/
    qa.md                   how QA works on this product
  checkout/                 one module: a page or an area
    _skill.md               selectors, data model, states, gotchas
    _roles/
      qa.md                 the module's own test playbook
  ops/
    example_create_order.yaml   a workflow

Part	Rule
Domain folder	Named after the host (app.example.com) or a short slug for a knowledge area. Every top-level folder that does not start with _ is a domain.
Module folder	A subfolder of a domain with its own _skill.md. Modules can nest.
_roles/	Role guides, at the repository root (account-wide), in a domain, or in a module. A file here is what registers a role on your account. See Roles and personas.
_souls/	Personas, at the repository root only. They add no domain and register no role.
Workflows	*.yaml files in a domain. Workflows the app creates go to <domain>/ops/<id>.yaml.
index.json	Lists the repository's packs. Kept up to date for you; never edit it by hand.

A file can be at most 512 KB.

The manifest: skill-pack.json

{
  "name": "example-app",
  "version": "1.0.0",
  "title": "Example App Storefront",
  "description": "Checkout, orders and account pages of the Example App storefront",
  "domain": "app.example.com",
  "requires": { "browser": true, "llm": true },
  "roles": ["se", "qa"]
}

name, version and domain are required. domain is what the agent runtime matches pages against; name is a lower-case, kebab-case slug without a top-level domain (example-app, not app.example.com).

The knowledge: _skill.md

Each _skill.md starts with YAML frontmatter, followed by Markdown.

---
name: Example App Storefront
domain: app.example.com
confidence: 0.6
workspaces: ["storefront"]
repos:
  - repo: example-org/storefront
    subpath: web
tags: ["@checkout", "@payments"]
---

Field	What it does
name	The name agents and the app show.
domain	The domain the file belongs to.
match	Optional URL patterns; defaults to the domain.
confidence	0 to 1: how complete and verified this file is. It drives the domain's readiness.
workspaces	On a domain root: the workspaces (by slug) this domain belongs to.
repos	The repositories, and the folder inside each, that implement this domain or module.
tags	Free tags for grouping.

confidence, repos and workspaces are what Skill Discovery reads and writes. The app accepts a save without them but warns you, because the metadata is lost.

Role files

A role file is Markdown with a short frontmatter:

---
name: QA Engineer
match:
  - app.example.com
---

The body says how the role works in that domain or module: what to check, what evidence a verdict needs, and which workflows to use. A module's role file adds to the domain's, and the domain's adds to the account-wide guide of the same role.

Workflows

A workflow is YAML with at least an id, a title and steps, and every step type must be one the engine runs. The app checks this whenever a workflow is saved and shows each error with its step, line and column. A workflow that stops passing at a sync keeps running its last good version and is flagged invalid. For the format, see Workflows and the DSL reference.

id: example_view_order
title: "View Order Details Page"
description: "Open one order in the Example App and snapshot it"
params:
  order_id: string
steps:
  - type: browser.navigate
    url: "https://app.example.com/orders/{{order_id}}"
  - type: browser.snapshot
    as: order
    includeContent: true

Naming

The public library's naming rules keep titles readable wherever a pack is listed. Follow them in your own packs too.

Field	Length	Example
Pack title (skill-pack.json title)	18–35 characters	LinkedIn Outreach Platform
Role name (role file name)	15–30 characters	Sales Development, Project Manager
Module name (module _skill.md name)	15–30 characters	Campaign Diagnostics, Reports & Dashboards
Workflow title	15–30 characters	Draft Message Reply

• Pack titles are noun phrases naming the platform and its role: {Platform} {Descriptor}, {Platform} {Product} or {Capability} Standards. Avoid a bare platform name.
• Role names are full job titles, never abbreviations: Project Manager, not PM.
• Module names describe a capability area, not a lone noun: Content Quality, not Quality.
• Workflow titles follow {verb} {object} [{context}]: Scan Feed for Mentions, not Scan.
• No word twice in {child name} · {pack title}: Content Writer · Writing Standards, not Content Writer · Content Writing.
• One name everywhere: the title in index.json and skill-pack.json, and the name and first heading of the domain's _skill.md, must match.

The full rules are in the library's NAMING.md.

How agents read a pack

Files lower in the tree extend the ones above them, so an agent loads a pack top-down before it works on a feature:

Order	File	What it gives the agent
1	<domain>/_skill.md	Sign-in, navigation and the product's global context
2	<domain>/_roles/<role>.md	The role's rules for this product: evidence standards, data handling, automation
3	<domain>/<module>/_skill.md	The module's selectors, data model and states
4	<domain>/<module>/_roles/<role>.md	The role's instructions for this module

The domain's role file carries the rules that hold everywhere, so it is always read before any module file. Write each file so it makes sense after the ones above it, without repeating them.

Writing knowledge an agent can act on

Write _skill.md as if you were onboarding a new colleague who has never seen the product. Put in the details that would take hours of exploring to find.

Quality	What to document	Why it matters
Selectors inside each section	Data attributes, ARIA roles and scoping selectors for the inputs, buttons and displays inside each part of a page, not only the top navigation	One view often holds several forms, tabs or panels; the agent must target the right one
States	Every state an entity can be in, what moves it between states, and how the page shows each (badges, conditional fields, disabled controls)	Without a state map an agent cannot tell "working" from "silently broken"
Interaction gotchas	Field order dependencies, elements that appear only after another action, inputs that silently reject values	These sequences are invisible in the markup and are where agents get stuck
Caching and timing	How long data stays stale, which actions refresh a view, which need a reload	An agent that checks too early reports a false failure
Business rules	Formulas, aggregations, how derived values relate to their sources	To test a report the agent must know what the right number is, not only that a number exists

Keep each file honest about its confidence: raise it when a section is verified against the live product, and leave it lower when it is a first pass. Readiness, and the warnings on jobs, are only as good as these numbers.

Publishing to your account's repository

Your agents and the app read only the repository's tracked branch, which is main unless you chose another one on Settings › Skill Pack Repository. Publishing is a push to that branch. There is no separate publish step and no version bump: the app re-syncs from the latest commit, and agents install the change on their next sync, within about 5 minutes.

• Your own repository (GitHub, GitLab or Bitbucket): commit and push with your usual git access. A change on another branch, or in a pull request, reaches nobody until it is merged into the tracked branch.
• The portal-default repository: Kadmo hosts it for you; change it in the app, as below.
• Skill Discovery pushes its own commits straight to the tracked branch of either kind, with the agent's git access.

Settings › Skill Pack Repository › Sync Now pulls the latest commit into the app at once, without waiting for the next sync.

Editing in the app

An account admin can change any part of the pack in the app. Every save is a git commit authored as you, pushed to the repository and re-synced at once, so readiness, workflows and roles update immediately.

What	Where	How
A module or domain _skill.md	Settings › Library › Skill pack, a module	Edit on the file card, then Save & commit
Any other pack file	Skill pack, Files tab	Open the file, edit, save
A new module or domain	Skill pack	+ Module (a module slug under an existing domain) or + Domain (a host such as app.example.com; seeds its _skill.md, its skill-pack.json and a QA role stub)
A role guide	Settings › Library › Roles, a role	Edit, or Create playbook file when the role has none
A new role	Roles	+ New role (see Roles and personas)
A workflow	Settings › Library › Workflows	Edit YAML on the row, or Add workflow for a new one
A domain or module you no longer need	Skill pack	Delete domain… or Delete module… in the card's menu

Every create and save takes an optional Commit message.

Who can edit. You need the admin role, and an account whose trial has ended cannot edit until it has a plan. On your own repository the app writes only when Portal write access is Commit or Pull request; in Pull request mode a save opens a pull request instead of committing to the tracked branch, and the change reaches agents once you merge it. When editing is not possible, the disabled button tells you why.

Checks on save. A save is all or nothing:

1. The file is checked first: a skill-pack.json must be valid JSON with name, version and domain; a workflow must pass the workflow check; any other YAML must parse. A failing file is refused with the reasons, and nothing is written.
2. The app pulls the latest commit. If the file changed since you opened it (Skill Discovery writes to the same repository), the save is refused, your text is kept, and View the latest version shows what changed so you can save again.
3. The commit is pushed and the pack re-syncs.

Renaming a file is not available in the app; rename it in git.

Related

• Skill packs: layers, Skill Discovery and updates.
• Roles and personas: how a pack ships a role.
• Workflow examples: complete workflows to start from.