OpenSkillIndex← back to search
claude-code

Hash writing-hashql-diagnostics

HashQL diagnostic writing patterns using hashql-diagnostics crate. Use when creating error messages, warnings, Labels, Messages, Severity levels, Patches, Suggestions, or improving diagnostic quality in HashQL code.

install
source · Clone the upstream repo
git clone https://github.com/hashintel/hash
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/hashintel/hash "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/writing-hashql-diagnostics" ~/.claude/skills/hashintel-hash-writing-hashql-diagnostics && rm -rf "$T"
manifest: .claude/skills/writing-hashql-diagnostics/SKILL.md
source content

HashQL Diagnostic Writing

Provides HASH-specific patterns for writing high-quality diagnostics using the 

hashql-diagnostics
crate, ensuring messages are helpful, actionable, and follow consistent style conventions.

Core Principles

Diagnostics should be helpful, not just correct:

✅ DO:

  • Start messages with lowercase
  • Use backticks for code elements: 
    expected `bool`, found `String`
  • Make messages actionable and specific
  • Use "invalid" not "illegal"
  • Keep help messages as imperatives: "add type annotations"

❌ DON'T:

  • End messages with punctuation (unless multi-sentence)
  • Use apologetic language ("sorry", "unfortunately")
  • Write vague messages ("something went wrong")
  • Capitalize message starts (unless code identifier)

Quick Reference

Creating a Diagnostic

use hashql_diagnostics::{Diagnostic, Label, Message, Severity};

let mut diagnostic = Diagnostic::new(category, Severity::Error)
    .primary(Label::new(span, "expected `bool`, found `String`"));

diagnostic.add_label(Label::new(other_span, "expected because of this"));
diagnostic.add_message(Message::help("try using a comparison"));

Severity Levels

SeverityWhen to Use
Bug
Internal compiler error
Fatal
Unrecoverable error
Error
Must be fixed to compile
Warning
Suspicious code to review
Note
Informational context

Message Style

// ✅ Good
"cannot find variable `count` in this scope"
"expected `;` after expression"

// ❌ Bad
"Error: Variable not found."  // capitalized, punctuation
"Sorry, there's a type mismatch"  // apologetic

Adding Suggestions

use hashql_diagnostics::{Message, Patch, Suggestions};

let suggestion = Suggestions::patch(Patch::new(span, "corrected_code"));
diagnostic.add_message(
    Message::help("fix the typo").with_suggestions(suggestion)
);

References