robotter 0.17.3

Project:

Package:

Development:

Contents

• Overview
  • Rendering a template
    • Example Configuration
  • Rendering a skill
    • Example Skill
  • Editing an agent's configuration
  • Editing a skill
  • Browsing an agent's global configuration
  • Browsing an agent's skills
• Installation
• Development
• Additional Information
• License

Overview

robotter composes GenAI "dotfiles" (the instruction/configuration files read by AI coding agents) from a single source template.

Different agents read their configuration from different locations under different filenames. robotter renders one Jinja2 template and writes the result to the appropriate location(s) for a target agent, at either global (user-level) or project scope:

Some agents also support "skills" — reusable instruction sets stored under a per-skill location, keyed by a skill name. robotter writes rendered skills to the appropriate location(s) for those agents:

Templates may include optional YAML frontmatter (preserved in the rendered output) and may compose other templates via the include_configuration("<relative path>") function, letting you maintain shared content once and assemble agent-specific files from it (see Example Configuration and Example Skill below).

How to use robotter

Render a template to an agent's configuration location(s):

uvx robotter render <template> <agent> [<dir>] [--verbose] [--debug]

Examples

Render instructions.md to the current user's global Claude Code configuration:

uvx robotter render instructions.md claude-code

Render instructions.md to the project-level OpenCode configuration under ./my-project:

uvx robotter render instructions.md opencode ./my-project

Example Configuration

A configuration file is a Jinja2 template with optional YAML frontmatter. Use the include_configuration("<relative path>") function to compose shared content from another configuration file, letting you maintain that content once and reuse it across multiple templates.

The following instructions.md template includes a shared shared/coding-standards.md file:

---
description: Instructions for AI coding agents
---
# Project Instructions

## Overview
This project composes GenAI dotfiles from a single source template.

## Coding Standards
{{ include_configuration("shared/coding-standards.md") }}

The included shared/coding-standards.md file (its frontmatter, if any, is ignored when included):

- Prefer clarity over cleverness.
- Write tests for all new functionality.
- Document public interfaces.

The path passed to include_configuration is resolved relative to the file that contains the call, so a template in one directory can include a file located in a subdirectory ("shared/coding-standards.md") or a parent directory ("../coding-standards.md"). Included files may themselves call include_configuration, allowing configuration to be composed from arbitrarily nested fragments.

Rendering the instructions.md template above produces the following output (the frontmatter is preserved; the include_configuration call is replaced with the rendered content of the included file):

---
description: Instructions for AI coding agents
---
# Project Instructions

## Overview
This project composes GenAI dotfiles from a single source template.

## Coding Standards
- Prefer clarity over cleverness.
- Write tests for all new functionality.
- Document public interfaces.

Rendering a skill

Some agents support "skills" — reusable instruction sets stored under a per-skill location. Render a skill template to an agent's skill location(s):

uvx robotter render_skill <template> <agent> [<dir>] [--verbose] [--debug]

The skill name is taken from the template's frontmatter name attribute (required); the rendered output is written to the per-skill location derived from that name (see the table in the Overview above). Not every agent supports skills; render_skill fails for an agent that does not.

Example Skill

A skill template is a Jinja2 template with YAML frontmatter that must include a name attribute; that name determines the per-skill location the rendered output is written to. Like a configuration template, a skill template may compose shared content via include_configuration("<relative path>").

The following review_skill.md skill template declares its name in frontmatter and reuses the shared shared/coding-standards.md file from the Example Configuration above. Note that the template filename (review_skill.md) and the name attribute (review) are independent — the rendered output location is derived from name, not the filename:

---
name: review
description: Review changes before committing
---
# Review

Review the pending changes before committing, confirming they satisfy the project's coding standards:

{{ include_configuration("shared/coding-standards.md") }}

Rendering the template preserves the frontmatter and replaces the include_configuration call with the rendered content of the included file, producing the following SKILL.md:

---
name: review
description: Review changes before committing
---
# Review

Review the pending changes before committing, confirming they satisfy the project's coding standards:

- Prefer clarity over cleverness.
- Write tests for all new functionality.
- Document public interfaces.

Examples

Render review_skill.md to the current user's global Claude Code skill location (~/.claude/skills/review/SKILL.md):

uvx robotter render_skill review_skill.md claude-code

Render review_skill.md to the project-level Claude Code skill under ./my-project (./my-project/.claude/skills/review/SKILL.md):

uvx robotter render_skill review_skill.md claude-code ./my-project

Editing an agent's configuration

Open an agent's rendered configuration file in an editor:

uvx robotter edit <agent> [<dir>] [--verbose] [--debug]

The configuration file must already exist (for example, produced by a prior render); edit fails if it does not. The editor is selected from the VISUAL or EDITOR environment variable when set, otherwise the operating system's default handler for the file is used.

Examples

Edit the current user's global Claude Code configuration:

uvx robotter edit claude-code

Edit the project-level OpenCode configuration under ./my-project:

uvx robotter edit opencode ./my-project

Editing a skill

Open an agent's rendered skill file in an editor:

uvx robotter edit_skill <name> <agent> [<dir>] [--verbose] [--debug]

The skill file must already exist (for example, produced by a prior render_skill); edit_skill fails if it does not. The editor is selected from the VISUAL or EDITOR environment variable when set, otherwise the operating system's default handler for the file is used. Not every agent supports skills; edit_skill fails for an agent that does not.

Examples

Edit the current user's global Claude Code review skill (~/.claude/skills/review/SKILL.md):

uvx robotter edit_skill review claude-code

Edit the project-level Claude Code review skill under ./my-project (./my-project/.claude/skills/review/SKILL.md):

uvx robotter edit_skill review claude-code ./my-project

Browsing an agent's global configuration

Open an agent's global (user-level) configuration directory in a file browser:

uvx robotter browse <agent> [--verbose] [--debug]

The directory is opened using the operating system's default file browser. The directory must already exist (for example, produced by a prior render); browse fails if it does not.

Example

Browse the current user's global Claude Code configuration directory:

uvx robotter browse claude-code

Browsing an agent's skills

Open an agent's skills directory in a file browser:

uvx robotter browse_skills <agent> [<dir>] [--verbose] [--debug]

The directory is opened using the operating system's default file browser. The directory must already exist (for example, produced by a prior render_skill); browse_skills fails if it does not. Not every agent supports skills; browse_skills fails for an agent that does not.

Examples

Browse the current user's global Claude Code skills directory (~/.claude/skills):

uvx robotter browse_skills claude-code

Browse the project-level Claude Code skills directory under ./my-project (./my-project/.claude/skills):

uvx robotter browse_skills claude-code ./my-project

Installation

Note that it isn't necessary to install robotter when running via uvx.

Verifying Signed Artifacts

Artifacts are signed and verified using py-minisign and the public key in the file ./minisign_key.pub.

To verify that an artifact is valid, visit the latest release and download the .minisign signature file that corresponds to the artifact, then run the following command, replacing <filename> with the name of the artifact to be verified:

uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>'); print('The file has been verified.')"

Development

Please visit Contributing and Development for information on contributing to this project.

Additional Information

Additional information can be found at these locations.

License

robotter is licensed under the MIT license.