huml_skill

Overview

This skill lets you write, read, and validate HUML (Human-oriented Markup Language) documents. It provides conversion helpers from JSON/YAML/TOML to HUML, enforces HUML syntax rules, and returns clear validation errors. Use it when you need strict, human-readable configuration files with predictable parsing.

How this skill works

The skill parses .huml files and validates them against the HUML v0.2.0 specification: strict 2-space indentation, double-quoted strings, single-colon scalars, and double-colon vectors. It can convert JSON/YAML/TOML inputs into properly formatted HUML documents and run a validator that emits JSON output or detailed error messages. When asked about "huml" or human-readable alternatives to YAML, it explains syntax, common patterns, and best practices.

When to use it

• Creating or editing configuration files that must be unambiguous and human-friendly
• Converting existing JSON, YAML, or TOML configs into HUML format
• Validating .huml files before deployment or CI checks
• Generating templates for applications, services, or developer tools
• Checking HUML syntax and getting precise error locations

Best practices

• Always use 2-space indentation and never tabs to avoid parse errors
• Quote every string with double quotes; use triple quotes for multiline text
• Use single colon ':' for scalars and double colon '::' for lists/dicts with a required space after the punctuation
• Prefer explicit typing (numbers, booleans, null) instead of relying on implicit parsing
• Run the validator in CI to catch formatting and syntax problems early

Example use cases

• Convert a YAML service manifest to HUML for a more predictable config format
• Create a reusable HUML template for app settings and database credentials
• Validate a team-maintained .huml file and output parsed JSON for downstream tools
• Produce a list-of-objects HUML file for infrastructure definitions (servers, instances)
• Lint HUML files in a pre-commit hook to enforce style and indentation rules