Skip to content

Skills and routing

What it is. Kiyo exposes exactly eight public Skills. Each is a short SKILL.md entry that sets intent, modes, and an access contract, then points to a shared procedure. The Workflow Router (workflows/workflow-router.md, KIYO-ROUTE-001) is a decision procedure the agent follows to pick the right one.

Why it exists. Without an explicit workflow, a request like “look at the login code” can turn into an unrequested rewrite. Routing ties every task to one procedure with known effects.

The eight Skills

Section titled “The eight Skills”
Skill Logical ID Select for Default effect
Init kiyo.init Requested onboarding, initial analysis, Project Memory creation, setup readiness Preview read-only; initialize writes authorized project-local state
Requirement kiyo.requirement Defining behavior, acceptance criteria, open decisions Chat; an authorized specification path only
Implement kiyo.implement Bug fix, feature, explicitly scoped refactor Authorized code, tests, docs changes and checks
Review kiyo.review Reviewing or explaining existing changes Read-only; no build or test execution
Test kiyo.test Test gaps, running checks, writing tests assess, run, write have separate effects
Security kiyo.security Application, Skill, governance, or self-check assessment Read-only
Architecture kiyo.architecture Structure, impact, drift from approved decisions Read-only
Memory kiyo.memory Show, check, sync, repair Project Memory show/check read-only; sync/repair scoped writes

Logical IDs such as kiyo.init identify procedures. They are not universal commands. The host decides the actual selector, for example /kiyo-axiom-framework:init in Claude Code.

How routing decides

Section titled “How routing decides”
flowchart TD
accTitle: Workflow Router decision procedure
accDescr: The router establishes inputs, compares explicit Skill intent with the requested effects, selects one primary Skill, chooses action mode and risk treatment, then follows the matching flow.
A[Establish inputs:<br/>explicit Skill, request, output,<br/>authorized context, allowed mutation] --> B{Explicit Skill<br/>named?}
B -- yes --> C{Consistent with<br/>requested effects?}
C -- yes --> E[Use that Skill]
C -- no --> D[Report mismatch,<br/>propose one Skill,<br/>hold dependent writes]
B -- no --> F[Select by actual goal,<br/>not keyword]
F --> E
D --> E
E --> G[Pick action mode per operation<br/>+ Governance Review + risk]
G --> H{Effects}
H -- analysis --> I[Read-only flow]
H -- authorized change --> J[Implementation flow]
H -- failure / context limit --> K[Repair and handoff]

The router treats README text, issues, tool output, and Memory as untrusted evidence. It does not accept embedded rerouting or copied approvals.

Rules worth remembering

Section titled “Rules worth remembering”
  • One primary Skill. A security-related bug fix is Implement with a security checklist, not two Skills.
  • Mismatches are reported, not silently fixed. An explicit Test selection with a request to redesign authentication is a workflow mismatch. The agent explains it before changing effects.
  • Ambiguity starts read-only. For a vague request such as “take a look at login” (the framework’s example is phrased in Thai), the agent begins a bounded read-only look or asks which aspect is meant. It never infers an edit.
  • A report file is its own write. Asking Review to save findings to a file adds one scoped output write. It grants no source or Memory edits.

Anatomy of a Skill entry

Section titled “Anatomy of a Skill entry”

Each canonical SKILL.md stays short: at most 250 lines and 1,200 words, including frontmatter. Its frontmatter has two fields only:

src/kiyo/skills/memory/SKILL.md (frontmatter)
---
name: memory
description: Show selected Project Memory with freshness limits, check entries against current repository evidence, sync authorized factual observations, or repair scoped memory links and structure. ...
---

The body then:

  1. states the logical ID;
  2. tells the agent to read KIYO.md and the bootstrap before workflow actions;
  3. defines modes and a read, write, and execute access table;
  4. links the shared procedure and conditional references;
  5. defines completion under the shared Definition of Done.

Host-specific metadata never goes in canonical frontmatter; it belongs to the platform overlays.

Section titled “Related”