Skip to content
Maestria

Contributing

Contributing

Section titled “Contributing”

Thank you for your interest in contributing to @maestria/kimi-code! This guide covers project structure, editing skills, and submitting PRs.

For general development setup, changesets, and pull request workflow, see the Contributing Guide.

Project Structure

Section titled “Project Structure”

Unlike @maestria/opencode (TypeScript SDK with a src/index.ts entry point), @maestria/kimi-code is a declarative plugin - there is no build step and no source code. The “package source” is the manifest, the skill files, and the global rules.

maestria/
├── apps/
│   └── docs/                # Documentation site
└── packages/
    └── kimi-code/           # @maestria/kimi-code plugin
        ├── kimi.plugin.json # Plugin manifest (name, version, sessionStart.skill)
        ├── skills/          # SKILL.md files (orchestrator + 7 specialists)
        │   ├── orchestrator/
        │   ├── builder/
        │   ├── adventurer/
        │   ├── architect/
        │   ├── planner/
        │   ├── reviewer/
        │   ├── writer/
        │   └── diagnose/
        ├── rules/
        │   └── AGENTS.md     # Global rules (copied to ~/.kimi-code/AGENTS.md)
        ├── tests/            # Vitest assertions for manifest + safety
        ├── INSTALL.md        # Step-by-step setup checklist
        ├── README.md         # Overview
        └── CHANGELOG.md      # Release notes

Making Changes

Section titled “Making Changes”

Editing a skill

Section titled “Editing a skill”

Each specialist’s prompt is authored in the canonical source and synced to SKILL.md format via the sync pipeline. See Canonical Source Workflow in the Contributing Guide.

SKILL.md frontmatter reference

Section titled “SKILL.md frontmatter reference”
Field Type Description
name string Skill identifier (matches the directory name)
description string One-line role summary
type string Always "prompt" for persona content
whenToUse string Multi-line trigger phrases for the orchestrator
arguments array Optional positional arguments the skill accepts
disableModelInvocation boolean If true, only humans can invoke; the model cannot

Manifest reference

Section titled “Manifest reference”

The kimi.plugin.json manifest fields:

Field Type Description
name string Plugin identifier (maestria)
version string Semver version, follows the monorepo changeset pipeline
description string One-line summary for the plugin marketplace
keywords array Discovery keywords (maestria, kimi-code, swarm, etc.)
author object { name, email }
homepage string Project homepage URL
license string SPDX license identifier
skills string Path to the skills directory (e.g., "./skills/")
sessionStart.skill string Name of the skill to auto-load at session start (orchestrator)
skillInstructions string Plugin-wide instruction string injected alongside skills
interface object Display metadata (displayName, shortDescription, etc.)

Adding a new skill

Section titled “Adding a new skill”
  1. Create the canonical prompt - See Canonical Source Workflow in the Contributing Guide. No frontmatter needed - the canonical source is plain Markdown.
  2. Add a sync config entry - Add a new entry in packages/kimi-code/sync.config.ts specifying frontmatter (name, description, type, whenToUse triggers), the subagent type mapping (coder for write/edit access, explore for read-only, or plan for research-only), and add the new specialist to the orchestrator’s append section routing table.
  3. Add tests - Add vitest assertions in packages/kimi-code/tests/manifest.test.ts (or a new test file) to validate the new skill’s frontmatter and any safety constraints.
  4. Run vp test - Verify everything passes before submitting a PR.

Skill Prescription

Section titled “Skill Prescription”

Every skill’s SKILL.md follows a 4-section prescription pattern. This pattern keeps each specialist focused on its own methodology while routing edge cases to the right persona.

Section Purpose
Always load Skills this specialist’s role requires unconditionally (e.g., diagnose loads the diagnose methodology skill)
Load on trigger Conditional skills matched to specific situations (e.g., architect loads c4-architecture when a container diagram is needed)
Defer to specialist Skills that belong to a different persona’s domain (e.g., humanizer is the writer’s job, not the builder’s)
Skip if Conditions under which no skill load is needed at all (e.g., a 1-line fix, no new dependencies)

When writing or editing a skill, keep all four sections in the same order. The orchestrator’s Skill tool loads specialist skills on demand - the prescription sections are what the model uses to decide which additional skills to load.

See Also

Section titled “See Also”