Skills & roles

This page is the master list of every skill and role in folio-assistant, and explains how they fit together with the LLM. For the typed input/output contract of each skill, see the Skill schema reference.

How it works together with the LLM
Skills
Roles (actors)
Capabilities & requirements
See also

How it works together with the LLM

folio-assistant gives an LLM agent a structured way to do real authoring work. Five concepts compose:

flowchart TD
    LLM[LLM agent] -->|skill_list / skill_fetch| Skill[Skill<br/>schema-bounded unit of work]
    Skill --> Pkg[Skill package<br/>groups skills + Docker deps]
    Skill --> Schema[JSON Schema<br/>typed input/output]
    LLM --> Role[Role / actor<br/>who the agent acts as]
    Role -->|RBAC| Cap[Capabilities<br/>what the environment can do]
    Role --> Stage[Lifecycle stage<br/>plan→author→…→retire]
    Cap --> Req[Requirements<br/>gates that must hold]

Skill — a documented, schema-bounded unit of work (e.g. lean-formalization). The agent discovers skills with the skill_list MCP tool and loads a skill’s instructions with skill_fetch. Each skill has a typed input/output contract.
Skill package — a group of related skills that also declares its Docker/runtime dependencies (package-manifest.json).
Role (actor) — who the agent is acting as. An actor takes on a role because of the BPMN lane it acts in. What the actor may do is a W3C ODRL policy in policies/, not a property of the role. Before every task the executor checks authentication, role assignment, policy and content access (task-authorization); the HTTP routes ask the same policies through src/core/rbac.ts.
Capability — a concrete environment ability (e.g. latex-compiler, lean-toolchain). Skills require capabilities; check_dependencies probes them.
Requirement — a gate that must hold (e.g. commit-hygiene, lean-verification) before/while a stage proceeds.

The loop, in practice: the agent primes the work-plan (work_plan_prime), checks it has the capabilities it needs (check_dependencies), lists and loads the right skill (skill_list → skill_fetch), does the work as the user’s role (subject to RBAC), and validates/builds/publishes through the content adapter’s tools.

Skills

Where skills live (and their status)

A skill is defined across a few layers — not a single file. For any skill:

Layer	Location	Status
Definition (roles, required capabilities, requirements, routing patterns, lifecycle stages, schema ref)	`.claude/skills/local/<skill>.json`	✅ all 22 authoring skills — validated in CI by `scripts/validate-skills.ts`
Typed contract (input/output JSON Schema)	`schemas/skills/<skill>/`	✅ all 22 — see reference
Instruction body (prose how-to the LLM loads) — browse them in the Skill instructions reference	`skills/authoring/content-lifecycle/.md`, `skills/folio--adapter/.md`, `src/skills/.md`	✅ lifecycle, agent, platform-bundle and folio-document-adapter skills; ⏳ authoring-math / authoring-who-smart-guidelines bodies are TBD (those packages ship the manifest + JSON definitions)
Package (Docker/runtime deps)	`skills/<package>/package-manifest.json`	✅ all four packages

So yes, the skills exist — as structured definitions + typed schemas, with prose bodies shipped for the lifecycle and agent skills. The skill_fetch MCP tool currently serves the src/skills/*.md bodies; the authoring-skill prose bodies are the next thing to fill in (the definitions and contracts they’d attach to are already in place).

Cross-cutting: `content-lifecycle`

The lifecycle stages that apply to every content type:

Skill	Stage	Purpose
`content-plan`	plan	Scope, team, timeline, governance
`content-author`	author	Create structured artifacts
`content-validate`	validate	Check schema + constraints
`content-review`	review	Formal review & approval
`content-test`	test	End-to-end QA / build green
`content-publish`	publish	Render & deploy
`content-feedback`	feedback	Collect & triage feedback
`content-retire`	retire	Deprecate / archive

Documents & policy guidance: `folio-document-adapter`

Skill	Purpose
`document-authoring`	Create and revise blocks in a prose folio
`document-structure`	Chapters and sections — add, remove, reorder
`normative-statements`	Carry a recommendation, requirement or rule
`document-publishing`	Markdown → HTML / PDF, no TeX

Papers & books: `authoring-math`

Skill	Purpose
`lean-formalization`	Formalize statements/proofs in Lean 4
`latex-authoring`	Author LaTeX documents
`proof-verification`	Verify proofs, audit `sorry`/axioms
`scientific-visualization`	Figures & diagrams
`hypothesis-generation`	Propose conjectures / directions
`scientific-critical-thinking`	Adversarial review of arguments

WHO SMART Guidelines: `authoring-who-smart-guidelines`

Skill	Purpose
`l2-dak-authoring`	L2 DAK artifacts (data dictionary, etc.)
`l3-fhir-authoring`	L3 FHIR resources via FSH
`bpmn-authoring`	BPMN 2.0 business processes
`dmn-authoring`	DMN decision tables
`terminology-management`	Code systems / value sets
`fhir-validation`	Validate against FHIR profiles
`ig-publication`	Build & publish the IG
`quality-control`	QA gates

Agent/platform skills (`src/skills`)

Skills the LLM uses to work effectively in the repo (loaded via skill_fetch, package folio-assistant):

Skill	Purpose
`corpus-grep`	Search across the content corpus

editor, readability-editing, todo-review, symbiotic-interaction, and deployment-auth now live (generalized) in the folio-core bundle below — fetch them with package_name="folio-core".

A paper folio wants the folio-document-adapter skills too: a paper is a document plus Lean-bearing blocks, so document-structure and document-publishing apply to both. The two bundles are halves of one content model, not alternatives to choose between.

Local coordination skills (`.claude/skills/local`)

Skill	Purpose
`prepare-merge`	Take a branch to clean/green/mergeable (see also `/watch`)
`bean-coordination`	Multi-agent claim/coordination discipline
`todo-manager`	beans-as-todos discipline

Platform skill bundles (`skills/folio-core`, the content core’s `skills/content/folio-document-adapter`, the science layer’s `skills/content/folio-paper-adapter`)

Larger platform bundles, two of them migrated from the qou content repo (see migration record and issue #27). These are content-agnostic and meant to be synced into any folio:

Bundle	Skills	Scope
`folio-core`	43	Agent coordination, the watcher framework, QA / render / bibliography / glossary pipeline, docs, deployment — applies to any content type.
`folio-document-adapter`	4	Prose folios: block authoring, chapter/section structure, normative statements, and the TeX-free publication path. Applies to papers too.
`folio-paper-adapter`	40	Formal-math paper-adapter (any Lean 4 + LaTeX paper): Lean workflow, proof tooling, content-object validation, LaTeX, paper structure, import, simulators.

Irreducible QOU physics skills were skipped; QOU-specific examples in the rest were generalized. Each bundle ships a package-manifest.json.

Skill schemas (typed input/output for the authoring skills) are generated into the Skill schema reference — never drift from what the framework validates.

Roles (actors)

Roles answer who the agent is acting as. The current user is mapped to a role by role-assignments.json, and the role’s capabilities bound what the agent may do (RBAC). Roles inherit (e.g. author inherits reviewer).

To see these roles as lanes — who edits, who reviews, who signs off, and which steps an agent may take on its own — read Publication workflow → Who is who.

flowchart LR
    viewer --> reviewer --> author --> admin

People

Role	What they can do
`viewer`	Base read-only. View content, no changes.
`reviewer`	View + review comments; no direct changes.
`author`	Create/modify content (inherits reviewer).
`admin`	Full administrative access — roles, settings, all content.
`programme-manager`	Scope, team formation, timeline, stakeholder governance.
`technical-officer`	Programme-area coordinator + first-pass reviewer.
`business-analyst`	L2 DAK author (BPMN, data dictionaries, decision logic, indicators).
`clinical-sme`	Clinical validator / ground-truth provider.
`terminologist`	Terminology governance (ICD-11, SNOMED CT, LOINC).
`fhir-modeller`	L3 FHIR artifacts (FSH, SUSHI, CQL, IG Publisher).
`content-reviewer`	Formal approval / phase-transition sign-off.
`qc-reviewer`	Publication-readiness QA across layers.
`publication-manager`	Releases, IG config, builds, versioning, publication.
`translator`	Localization for UN-supported languages.

System actors

Actor	Provides	Cannot
`authoring-agent`	Drafts and revises a proposed change to a content block	Commit — its output goes to the editor through the validation gate
`review-agent`	Non-mechanical validation: accuracy, voice, exposition	Approve — it reports findings only
`lean-mcp`	Lean 4 proof checking & diagnostics via MCP	—
`ig-publisher-service`	FHIR IG Publisher build & QA reporting	—

Where each of these sits in the process — and what an agent may and may not decide — is modelled in the publication workflow BPMN diagrams.

Role assignment

role-assignments.json maps a user identity (from git config / auth) to a role by priority. The shipped defaults:

Pattern	Source	Role	Priority
`litlfred@gmail.com`	git-config	`admin`	100
`*@who.int`	git-config	`author`	50
`*`	default	`viewer`	0

Capabilities & requirements

Capabilities are concrete environment abilities a skill may require; the check_dependencies MCP tool probes them:

bun-runtime · node-runtime · python3 · git-push · docker · latex-compiler · lean-toolchain · lean-mcp · ig-publisher · sushi-compiler · java-runtime · jekyll · plantuml · graphviz

Requirements are gates that must hold during work:

commit-hygiene · lean-verification · fhir-validation · content-lifecycle · session-start

Skills & roles

How it works together with the LLM

Skills

Where skills live (and their status)

Cross-cutting: content-lifecycle

Documents & policy guidance: folio-document-adapter

Papers & books: authoring-math

WHO SMART Guidelines: authoring-who-smart-guidelines

Agent/platform skills (src/skills)

Local coordination skills (.claude/skills/local)

Platform skill bundles (skills/folio-core, the content core’s skills/content/folio-document-adapter, the science layer’s skills/content/folio-paper-adapter)