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.
Best use case
writing-hashql-diagnostics is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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.
Teams using writing-hashql-diagnostics should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/writing-hashql-diagnostics/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How writing-hashql-diagnostics Compares
| Feature / Agent | writing-hashql-diagnostics | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
# 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
```rust
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
| Severity | When 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
```rust
// ✅ 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
```rust
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
- [Comprehensive guidelines](references/guidelines.md) - Complete message style guide, span selection, category design, label usage, help vs note, suggestion quality, review checklist
- [HashQL testing skill](../testing-hashql/SKILL.md) - For compiletest coverageRelated Skills
writing-hashql-jexpr
HashQL J-Expr syntax for writing queries. Use when writing J-Expr code, using #literal/#struct/#list constructs, understanding function call syntax, or working with HashQL query files (.jsonc).
testing-hashql
HashQL testing strategies including compiletest (UI tests), unit tests, and snapshot tests. Use when writing tests for HashQL code, using //~ annotations, running --bless, debugging test failures, or choosing the right testing approach.
zod
Zod v4 TypeScript schema validation patterns and best practices. Use when writing or modifying Zod schemas, adding schema annotations/metadata, or validating data with Zod.
skill-creator
Guide for creating effective Agent Skills. Use when users want to create a new skill (or update an existing skill) that extends an AI agent's capabilities with specialized knowledge, workflows, or tool integrations. Covers skill structure, YAML frontmatter, trigger configuration, and the 500-line rule.
panda-css
Panda CSS styling framework guidance. Use when working with @pandacss packages, styled components, design tokens, or responsive/conditional styles.
mastra
Mastra TypeScript framework for AI agents with memory, tools, workflows, and RAG. Use when working with @mastra/* packages or building AI agents.
managing-git-workflow
Git workflow for HASH including branch naming, PR creation, and PR reviews. Use when creating branches, making commits, opening pull requests, or reviewing PRs.
managing-cargo-dependencies
Cargo.toml dependency management patterns for HASH workspace. Use when adding, updating, or removing dependencies, organizing Cargo.toml sections, configuring version pinning and default features, or managing public dependencies.
handling-rust-errors
HASH error handling patterns using error-stack crate. Use when working with Result types, Report types, defining custom errors, propagating errors with change_context, adding context with attach, implementing Error trait, or documenting error conditions in Rust code.
exploring-rust-crates
Generate Rust documentation to understand crate APIs, structure, and usage. Use when exploring Rust code, understanding crate organization, finding functions/types/traits, or needing context about a Rust package in the HASH workspace.
documenting-rust-code
Rust documentation practices for HASH codebase. Use when writing doc comments, documenting functions/types/traits/modules, creating error sections, using intra-doc links, or following rustdoc conventions.
ark-ui
Headless component library for React. Use when building UI components with @ark-ui/react, implementing accessible form inputs, overlays, navigation patterns, or needing guidance on Ark UI's data attributes, composition (asChild), and state management patterns.