Skip to content

Activation and loading

What it is. The rules for how Kiyo’s instructions reach the agent, and how honestly that is reported. Defined in framework/activation-contract.md (KIYO-ACT-001) and framework/context-loading.md (KIYO-LOAD-001, KIYO-LOAD-002).

Why it exists. “The plugin is installed” is often mistaken for “the agent follows the rules”. Kiyo treats them as separate facts with separate evidence. It never adds a hook, runtime, or MCP server to simulate always-on loading.

Four activation capabilities

Section titled “Four activation capabilities”
Capability What establishes it What it does not establish
Explicit Skill invocation You select an available native Skill entry with the host’s evidenced syntax Automatic Core loading, successful execution, or approval of every action
Implicit Skill selection An observed host selection for a particular prompt and configuration Explicit invocation, or reliable selection for future prompts
Automatic Core loading Target-specific evidence that a native facility loaded the Core That all sessions or targets load it, or that the agent obeyed every control
Agent-directed Core read An actual read of the packaged bootstrap after selection Native automatic loading or permanent installation

Evidence labels used throughout the documentation:

Label Meaning
DOCUMENTED_ONLY Supported by checked native documentation, not a Kiyo test
NOT_TESTED No live test of that capability on the stated target
UNKNOWN Insufficient or conflicting evidence
UNSUPPORTED An applicable source explicitly establishes the limit
VERIFIED An actual recorded observation, limited to the conditions tested
NOT_REVALIDATED A freshness qualifier for a source not rechecked

The loading order

Section titled “The loading order”

The logical order is bootstrap → selected Skill procedure → relevant references. Host discovery happens first. A host may open SKILL.md before the agent can follow its instruction to read the bootstrap; static Markdown cannot change that order.

sequenceDiagram
accTitle: Kiyo loading sequence
accDescr: The host discovers Skill metadata, the user selects a Skill, the agent reads SKILL.md, then KIYO.md and the bootstrap, then the selected procedure and only relevant references and one template, then produces output.
participant U as User
participant H as Host agent
participant S as SKILL.md
participant C as KIYO.md + bootstrap
participant R as Relevant references
H->>H: Discover name + description
U->>H: Select Skill and state intent
H->>S: Read entry (modes, access contract)
S->>C: "Read KIYO.md and its bootstrap before workflow actions"
C->>R: Selected procedure, then only needed references
R-->>H: One template for the report
H-->>U: Scoped work + chat report

Links are locators, not imports. The bootstrap does not recursively load every file it links. A missing or denied reference is reported with its path, and dependent actions stop. The agent never fetches a replacement Core from the network or runs a generator.

Context budgets

Section titled “Context budgets”

These are Kiyo’s authoring ceilings (KIYO-LOAD-002), not vendor limits or token counts. Lines count blanks and frontmatter; words split on whitespace.

Material Ceiling Measured at revision 897516e
KIYO.md + framework/bootstrap.md 120 lines, 600 words 81 lines, 581 words
Each rendered SKILL.md 250 lines, 1,200 words largest (Implement): 98 lines, 807 words
Kiyo-owned project instruction block 250 words samples recorded at 108–116 words

Per-Skill measurements are on Context budgets.

Persistent project guidance

Section titled “Persistent project guidance”

Installing a package exposes metadata; it does not make the Core always-on. If you want every session in a project to point at Kiyo state, an authorized Init can add a small managed block to the host’s own instruction file:

Host Project instruction file used for the block
Claude Code Existing CLAUDE.md or .claude/CLAUDE.md (a plugin-root CLAUDE.md is not project context)
Codex CLI The applicable AGENTS.md chain; AGENTS.override.md and global config are never edited
GitHub Copilot .github/copilot-instructions.md, AGENTS.md, or path-specific instructions

The block has <!-- KIYO:BEGIN project-context --> and <!-- KIYO:END project-context --> markers, an adapter revision (init-locator-1, a text-format revision, not a product version), and project-relative locators. It stays within 250 words and never copies the Core. After insertion it is your file content. Plugin updates and uninstall never modify or remove it.

Whether any host loads that block automatically in a fresh session is NOT_TESTED.

Section titled “Related”