OpenParable
Skip to content
← Back to skills

Syntax Definition

Development
syntax-definition

Syntax Definition is an Agent Skill for development 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 Sublime Text 3 compatible `.sublime-syntax` grammar in the repository `syntaxes/` directory when asked for a specific language or format such as JSON, TypeScript, Elm, or Dockerfile.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/jmacdonald/amp/blob/HEAD/.agents/skills/syntax-definition/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/syntax-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.

Syntax Definition

Use this skill when asked to create or update a syntax definition for a named language or file format.

Goal

Create or update exactly one grammar file in the repository top-level syntaxes/ directory:

  • syntaxes/<Language>.sublime-syntax

Also create or update one fixture/expectations pair under tests/fixtures/syntaxes/<language>/:

  • <sample>.<ext>
  • <sample>.<ext>.tokens.yml

Examples:

  • JSON -> syntaxes/JSON.sublime-syntax
  • TypeScript -> syntaxes/TypeScript.sublime-syntax
  • Elm -> syntaxes/Elm.sublime-syntax
  • Dockerfile -> syntaxes/Dockerfile.sublime-syntax

If a matching file already exists, update it instead of creating a duplicate.

Required Constraints

  • Only produce Sublime Text 3 compatible grammars.
  • Do not use Sublime Text 4+ only syntax features.
  • Keep the file as YAML with the usual .sublime-syntax structure.
  • Do not write the grammar anywhere except the top-level syntaxes/ directory unless the user explicitly asks for something else.
  • Keep syntax regression fixtures under tests/fixtures/syntaxes/.

When compatibility is uncertain, prefer conservative syntax features:

  • %YAML 1.2
  • name
  • file_extensions
  • scope
  • variables
  • contexts
  • match
  • captures
  • scope
  • push
  • set
  • pop
  • include
  • meta_scope
  • meta_content_scope

Workflow

  1. Identify the requested language or format name.
  2. Inspect nearby files in syntaxes/ to match the repository's existing style and naming conventions.
  3. Create a practical first-pass grammar with the core building blocks for that language:
    • comments
    • strings
    • numbers
    • keywords
    • operators or punctuation
    • identifiers
  4. Add one representative sample file under tests/fixtures/syntaxes/<language>/.
  5. Add a YAML expectations file named <sample>.<ext>.tokens.yml with:
    • buffer_path: the virtual filename used to select the syntax
    • expectations: an ordered list of critical (text, scope) checks
  6. Run cargo test syntaxes to test and fix issues with the generated/updated syntax.

Output guidelines

For generated/updated syntaxes

  • Use a stable top-level scope such as source.<language> or text.<format> as appropriate.
  • Keep contexts readable and modular rather than over-optimizing the grammar.
  • If the language details are incomplete, make the smallest reasonable set of assumptions and state them briefly.
  • The resulting syntax file should be directly usable by the repository's syntax-loading code.
  • Prefer correctness and compatibility over advanced grammar tricks.

For syntax fixtures

  • Use critical-scope expectations only; do not snapshot every token unless the user explicitly asks for exhaustive coverage.
  • The fixture should be directly usable by the repository's scribe::Workspace.current_buffer_tokens() test harness.