Theme Definition
Designtheme-definitionTheme Definition is an Agent Skill for design published in the jmacdonald/amp repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Create or update a bundled YAML theme source in the repository `themes/` directory when asked for a specific color theme such as Gruvbox, Nord, or a custom dark or light palette. These YAML files are compiled into TextMate `.tmTheme` files during the build.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/jmacdonald/amp/blob/HEAD/.agents/skills/theme-definition/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/theme-definition, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Theme Definition
Use this skill when asked to create or update a bundled theme definition for a named color theme or palette.
Goal
Create or update exactly one bundled theme source file in the repository top-level themes/ directory:
themes/<theme-name>.yml
Examples:
Gruvbox Dark->themes/gruvbox_dark.ymlNord Light->themes/nord_light.ymlMy Theme->themes/my_theme.yml
If a matching file already exists, update it instead of creating a duplicate.
The YAML source is the authored artifact. Amp's build compiles it into a generated .tmTheme file with the same key during build.rs.
Required Constraints
- Only author bundled YAML theme sources in
themes/. - Do not manually create or edit generated
.tmThemefiles for bundled themes. - Do not write the theme anywhere except the top-level
themes/directory unless the user explicitly asks for something else. - Use the semantic token-family standard in references/token-color-standard.md whenever the user does not provide a custom scope map.
- Treat
paletteas the single source of truth for authored colors:- define hex literals in
palette - reference palette keys from
settingsandrules - do not place inline hex literals directly in
settingsorrules
- define hex literals in
- Match the actual compiler schema in
build/theme_compiler/:- required top-level keys:
name,settings,rules - optional top-level key:
palette palettevalues must be hex colors- required
settingskeys:foreground,background,line_highlight settings.foreground,settings.background, andsettings.line_highlightmust reference palette keysrulesmust not be empty- each rule may contain
name,scope,foreground,background,font_style rules[*].foregroundandrules[*].background, when present, must reference palette keys- each rule must define at least one of
foreground,background, orfont_style scopemust be a single valid TextMate selector stringfont_stylevalues arebold,italic, andunderline
- required top-level keys:
- Treat unknown YAML keys as invalid rather than inventing extra structure.
Amp requires these base theme settings:
settings.foregroundsettings.backgroundsettings.line_highlight
When the user does not provide a complete scope list, do not stop at a small "practical first pass". Map the requested palette onto the canonical token families in the reference file so common code tokens do not collapse to the default foreground.
Workflow
- Identify the requested theme name and whether it is dark, light, or otherwise palette-driven.
- Inspect nearby files in
themes/for filename and YAML rule-shape conventions. - Read references/token-color-standard.md and choose colors for each required family.
- Create or update a YAML theme source with:
- top-level
name - a
palettecontaining the authored hex colors settings.foreground,settings.background, andsettings.line_highlightas palette-key referencesrulescovering the canonical token families in the reference, using the requested palette
- top-level
- Prefer broadly useful TextMate scopes and stable fallback tiers instead of copying an existing bundled theme's exact rule list.
- Validate through the repository build path before finishing.
Output Guidelines
For Generated Or Updated Themes
- Use a filename stem that matches the theme key Amp will expose in theme selection.
- Keep the YAML concise and readable rather than encoding generated
.tmThemestructure by hand. - Put literal hex values in
palette, not directly insettingsor per-rule color fields. - If the requested palette is underspecified, make the smallest reasonable set of assumptions and state them briefly.
- Prefer semantically complete coverage over an artificially tiny rule set.
- Ensure the base settings are sufficient for Amp's UI color mapping:
settings.foregroundis used for default textsettings.backgroundis used for inverted background mappingssettings.line_highlightis used for the focused or current-line background
- Use the default foreground as a last-resort fallback, not as the intended color for common code tokens.
- Keep at least two punctuation tiers when the palette allows it:
- structural punctuation can stay muted
- semantic operators should remain clearly visible
- Distinguish the following families whenever the palette allows it:
- comments
- strings
- numbers and constants
- keywords and storage
- functions and methods
- types and namespaces
- local variables
- parameters
- support or builtin symbols
- annotations or attributes
- semantic operators
- structural punctuation
- Rust is a useful stress case for validation, but the output must remain cross-language and useful for markup and configuration formats too.
For Validation
- Prefer
cargo checkas the main smoke test. It runsbuild.rs, compilesthemes/*.yml, and loads the generated bundled themes. - Use
cargo test --test theme_compilerwhen validating compiler-schema behavior or debugging theme-source failures. - Treat inline color literals outside
paletteas source-format errors. - If there is no dedicated theme test for a specific change, still perform at least a build-path smoke check before finishing.
- When updating a bundled example theme, prefer adding or running a test that confirms the compiled theme loads and that key token families are represented by explicit scope rules.