Skip to content
Maestria

Contributing

Contributing

Section titled “Contributing”

Thank you for your interest in contributing to @maestria/claude-code! This guide covers project structure, the sync pipeline, and how to extend the plugin.

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

Project Structure

Section titled “Project Structure”

Like @maestria/kimi-code, @maestria/claude-code is a declarative plugin - there is no build step and no runtime source code. The “package source” is the manifest, the generated agent/skill/command files, and the sync config that produces them.

maestria/
├── apps/
│   └── docs/                # Documentation site
└── packages/
    ├── core/
    │   └── agent-directives/ # Canonical agent prompts (.md files) and rules.md
    └── claude-code/          # @maestria/claude-code plugin
        ├── .claude-plugin/
        │   └── plugin.json   # Plugin manifest (name, version, description)
        ├── agents/           # Generated specialist agents (do not edit directly)
        ├── skills/           # Generated SKILL.md files (do not edit directly)
        │   ├── orchestrator/
        │   └── global-rules/
        ├── commands/         # Generated workflow commands (do not edit directly)
        ├── tests/            # Vitest assertions for manifest + generated files
        ├── sync.config.ts    # Platform derivation: frontmatter, namespacing, restrictions
        ├── INSTALL.md        # Step-by-step validation/loading checklist
        ├── README.md         # Overview
        └── CHANGELOG.md      # Release notes


The repository-level `.claude-plugin/marketplace.json` is the host-CLI marketplace entry. It points
to the published npm package, while the package-level `.claude-plugin/plugin.json` describes the
plugin itself.

Making Changes

Section titled “Making Changes”

Editing agent prompts or global rules

Section titled “Editing agent prompts or global rules”

All methodology content is authored in the canonical source under packages/core/agent-directives/ and synced to Claude Code format via the sync pipeline. See Canonical Source Workflow in the Contributing Guide. Never hand-edit files under agents/, skills/, or commands/.

After changing canonical content, regenerate and verify from the repository root:

Terminal window
scripts/sync-all          # regenerate every platform package
scripts/check-sync        # CI check that generated files are in sync

Agent frontmatter reference

Section titled “Agent frontmatter reference”

Each specialist is a Markdown file with YAML frontmatter in packages/claude-code/agents/, derived by sync.config.ts:

Field Type Description
name string Agent identifier (adventurer, builder, …)
description string Role summary and when-to-use guidance
model string inherit - agents use the session model
skills array Skills preloaded into the agent (maestria:global-rules)
disallowedTools string Tools denied at runtime; Write, Edit on the three read-only roles only

Skill and command frontmatter

Section titled “Skill and command frontmatter”

Skills live in skills/<name>/SKILL.md. Fields: name, description, and user-invocable (set to false on global-rules, which is preload-only). Commands live in commands/<name>.md with name and description frontmatter.

Manifest reference

Section titled “Manifest reference”

The .claude-plugin/plugin.json manifest fields:

Field Type Description
name string Plugin identifier (maestria)
displayName string Human-readable plugin name (Maestria)
version string Semver version, follows the monorepo changeset pipeline
description string One-line summary
author object { name }
homepage string Project homepage URL
repository string Project repository URL
license string SPDX license identifier
keywords array Discovery keywords

Adding a new agent, skill, or command

Section titled “Adding a new agent, skill, or command”
  1. Create the canonical prompt in packages/core/agent-directives/ - plain Markdown, no frontmatter.
  2. Add a sync config entry in packages/claude-code/sync.config.ts specifying the output file, frontmatter (name, description, model, skills preload), and any read-only role prepend or disallowedTools restriction. The config also handles namespacing (maestria:<agent>) and Claude Code tool name casing.
  3. Add tests - add Vitest assertions in packages/claude-code/tests/plugin.test.ts to validate the new file’s frontmatter and any safety constraints.
  4. Run vp test - verify everything passes before submitting a PR.

Validating the plugin

Section titled “Validating the plugin”

Requires the Claude Code CLI (claude on PATH):

Terminal window
cd packages/claude-code
pnpm test          # manifest and generated-file assertions
pnpm validate      # claude plugin validate . --strict

pnpm validate runs claude plugin validate . --strict - --strict treats warnings as errors and is the current automated gate. Runtime behavior (skill preload resolution, command pipelines) is not yet tested end to end; see the runtime support matrix.

See Also

Section titled “See Also”