Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
8 changes: 4 additions & 4 deletions .claude/skills/documenting-rust-code/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ Use explicit `# Arguments` section:

### Module Documentation

```rust
````rust
//! Entity management functionality.
//!
//! Main types:
Expand All @@ -128,19 +128,19 @@ Use explicit `# Arguments` section:
//! ```
//! use hash_graph::entity::Entity;
//! ```
```
````

### Examples with Error Handling

```rust
````rust
/// # Examples
///
/// ```rust
/// let entities = get_entities_by_type(type_id)?;
/// assert_eq!(entities.len(), 2);
/// # Ok::<(), Box<dyn core::error::Error>>(())
/// ```
```
````

## Verification

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ With link definition:

### Basic Example Structure

```rust
````rust
/// # Examples
///
/// ```rust
Expand All @@ -89,7 +89,7 @@ With link definition:
/// assert_eq!(entity.id(), id);
/// # Ok::<(), Box<dyn core::error::Error>>(())
/// ```
```
````

### Example Checklist

Expand All @@ -105,7 +105,7 @@ With link definition:

Use `#` to hide necessary setup from docs display:

```rust
````rust
/// # Examples
///
/// ```rust
Expand All @@ -118,7 +118,7 @@ Use `#` to hide necessary setup from docs display:
/// # Ok(())
/// # }
/// ```
```
````

**What renders:**

Expand All @@ -133,34 +133,34 @@ println!("Found: {}", entity.name);

### Using `?` Operator

```rust
````rust
/// # Examples
///
/// ```rust
/// let result = fallible_operation()?;
/// assert!(result.is_valid());
/// # Ok::<(), Box<dyn core::error::Error>>(())
/// ```
```
````

### Using `expect` for Infallible Cases

```rust
````rust
/// # Examples
///
/// ```rust
/// let config = Config::default();
/// let value = config.get("key").expect("should have default key");
/// ```
```
````

---

## Multi-Step Examples

Show realistic usage patterns:

```rust
````rust
/// # Examples
///
/// ```rust
Expand All @@ -179,15 +179,15 @@ Show realistic usage patterns:
/// # Ok(())
/// # }
/// ```
```
````

---

## Module Documentation

Use `//!` for module-level docs:

```rust
````rust
//! Entity management functionality.
//!
//! This module provides types and functions for creating, updating,
Expand All @@ -208,7 +208,7 @@ Use `//!` for module-level docs:
//! store.save(&entity)?;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
```
````

---

Expand All @@ -234,7 +234,7 @@ Document performance characteristics when relevant:

## Async Documentation

```rust
````rust
/// Processes entity asynchronously.
///
/// # Concurrency
Expand All @@ -253,13 +253,13 @@ Document performance characteristics when relevant:
/// # }
/// ```
pub async fn process_async(&self, entity: Entity) -> Result<ProcessResult, Error> {
```
````

---

## Complete Example

```rust
````rust
/// Validates and creates entity with type checking.
///
/// Takes `properties` and validates them against the entity's type schema.
Expand Down Expand Up @@ -311,7 +311,7 @@ pub fn create_entity(
properties: Vec<(String, Value)>,
web_id: WebId,
) -> Result<EntityId, Report<EntityError>> {
```
````

---

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -212,7 +212,7 @@ Add `# Performance` sections for performance-critical functions:

## Complete Example

```rust
````rust
/// Validates and creates a new entity in the system.
///
/// Takes the provided `properties` and validates them against the entity's
Expand Down Expand Up @@ -265,7 +265,7 @@ pub fn create_entity(
web_id: WebId,
account: &Account,
) -> Result<EntityId, Report<EntityError>> {
```
````

---

Expand Down
8 changes: 4 additions & 4 deletions .claude/skills/handling-rust-errors/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,10 @@ Code in `libs/@local/hashql/*` uses the `hashql-diagnostics` crate instead of `e

**Which approach to use:**

| Location | Error Handling |
|-----------------------------------------|-----------------------------------------------------------------------------------------------------------|
| `libs/@local/hashql/*` (compiler code) | Use `hashql-diagnostics` β†’ See [writing-hashql-diagnostics](../writing-hashql-diagnostics/SKILL.md) skill |
| Everywhere else | Use `error-stack` patterns from this skill |
| Location | Error Handling |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `libs/@local/hashql/*` (compiler code) | Use `hashql-diagnostics` β†’ See [writing-hashql-diagnostics](../writing-hashql-diagnostics/SKILL.md) skill |
| Everywhere else | Use `error-stack` patterns from this skill |

Traditional `error-stack` patterns still apply for HashQL infrastructure code (CLI, file I/O, configuration) that doesn't involve compiler diagnostics.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ pub fn create_web(&mut self) -> Result<WebId, Report<WebError>> {

- `# Errors` section header
- Bullet point for each error variant
- Intra-doc links using `` [`VariantName`] `` syntax
- Intra-doc links using ``[`VariantName`]`` syntax
- Link definitions at the bottom

---
Expand Down Expand Up @@ -227,7 +227,7 @@ When writing `# Examples` sections for fallible functions:

Use `?` for error propagation in examples whenever possible:

```rust
````rust
/// Fetches and processes user data.
///
/// # Examples
Expand All @@ -242,7 +242,7 @@ Use `?` for error propagation in examples whenever possible:
pub fn fetch_user(id: &str) -> Result<User, Report<UserError>> {
// Implementation
}
```
````

**Key Points:**

Expand All @@ -254,7 +254,7 @@ pub fn fetch_user(id: &str) -> Result<User, Report<UserError>> {

Only use explicit error handling when demonstrating error handling itself:

```rust
````rust
/// Validates user input.
///
/// # Examples
Expand All @@ -269,7 +269,7 @@ Only use explicit error handling when demonstrating error handling itself:
pub fn validate_input(input: &str) -> Result<(), Report<ValidationError>> {
// Implementation
}
```
````

---

Expand Down Expand Up @@ -298,7 +298,7 @@ pub fn validate_input(input: &str) -> Result<(), Report<ValidationError>> {

### Complete Function Documentation

```rust
````rust
#[derive(Debug, derive_more::Display)]
pub enum RegistrationError {
#[display("Email already registered")]
Expand Down Expand Up @@ -339,7 +339,7 @@ impl Error for RegistrationError {}
pub fn register_user(email: &str, password: &str) -> Result<UserId, Report<RegistrationError>> {
// Implementation
}
```
````

---

Expand Down
30 changes: 16 additions & 14 deletions .claude/skills/skill-creator/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,14 +76,14 @@ skill-name/

Every SKILL.md must have YAML frontmatter with required and optional fields:

| Field | Required | Description |
| ----- | -------- | ----------- |
| `name` | Yes | Max 64 chars. Lowercase letters, numbers, hyphens only. Must match directory name. |
| `description` | Yes | Max 1024 chars. Describes what the skill does and when to use it. |
| `license` | No | License name or reference to a bundled license file. |
| `compatibility` | No | Max 500 chars. Environment requirements (intended product, system packages, etc.). |
| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
| `allowed-tools` | No | Space-delimited list of pre-approved tools. (Experimental) |
| Field | Required | Description |
| --------------- | -------- | ---------------------------------------------------------------------------------- |
| `name` | Yes | Max 64 chars. Lowercase letters, numbers, hyphens only. Must match directory name. |
| `description` | Yes | Max 1024 chars. Describes what the skill does and when to use it. |
| `license` | No | License name or reference to a bundled license file. |
| `compatibility` | No | Max 500 chars. Environment requirements (intended product, system packages, etc.). |
| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
| `allowed-tools` | No | Space-delimited list of pre-approved tools. (Experimental) |

#### Trigger Configuration (metadata.triggers)

Expand All @@ -92,17 +92,17 @@ Skills can define auto-activation triggers in the `metadata.triggers` field:
```yaml
metadata:
triggers:
type: domain # "domain" (advisory) or "guardrail" (enforced)
enforcement: suggest # "suggest", "warn", or "block"
priority: high # "critical", "high", "medium", or "low"
keywords: # Exact substring matches (case-insensitive)
type: domain # "domain" (advisory) or "guardrail" (enforced)
enforcement: suggest # "suggest", "warn", or "block"
priority: high # "critical", "high", "medium", or "low"
keywords: # Exact substring matches (case-insensitive)
- error
- Result
- error-stack
intent-patterns: # Regex patterns for intent detection
intent-patterns: # Regex patterns for intent detection
- "\\b(handle|create)\\b.*?\\berror\\b"
- "\\berror\\b.*?\\bhandling\\b"
files: # Optional: file-based triggers
files: # Optional: file-based triggers
include:
- "**/src/**/*.rs"
exclude:
Expand Down Expand Up @@ -166,9 +166,11 @@ Keep SKILL.md body under 500 lines. Split content into separate files when appro
# PDF Processing

## Quick start

Extract text with pdfplumber: [code example]

## Advanced features

- **Form filling**: See [FORMS.md](references/FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](references/REFERENCE.md) for all methods
```
Expand Down
8 changes: 4 additions & 4 deletions .claude/skills/skill-creator/assets/SKILL.template.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
name: {{skill_name}}
name: "{{skill_name}}"
description: "[TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]"
# license: Apache-2.0 # Uncomment and set license if needed
metadata:
triggers:
type: domain # "domain" (advisory) or "guardrail" (enforced)
enforcement: suggest # "suggest", "warn", or "block"
priority: medium # "critical", "high", "medium", or "low"
type: domain # "domain" (advisory) or "guardrail" (enforced)
enforcement: suggest # "suggest", "warn", or "block"
priority: medium # "critical", "high", "medium", or "low"
Comment on lines +7 to +9
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally, I liked the previous version more, but also don't feel strongly.

keywords:
- "[TODO: Add keywords that should trigger this skill]"
intent-patterns:
Expand Down
10 changes: 8 additions & 2 deletions .claude/skills/skill-creator/references/output-patterns.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,17 @@ ALWAYS use this exact template structure:
# [Analysis Title]

## Executive summary

[One-paragraph overview of key findings]

## Key findings

- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations

1. Specific actionable recommendation
2. Specific actionable recommendation
```
Expand All @@ -38,12 +41,15 @@ Here is a sensible default format, but use your best judgment:
# [Analysis Title]

## Executive summary

[Overview]

## Key findings

[Adapt sections based on what you discover]

## Recommendations

[Tailor to the specific context]

Adjust sections as needed for the specific analysis type.
Expand All @@ -67,7 +73,7 @@ feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

```text
````text

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Expand All @@ -81,6 +87,6 @@ Use UTC timestamps consistently across report generation
```text

Follow this style: type(scope): brief description, then detailed explanation.
```
````

Examples help agents understand the desired style and level of detail more clearly than descriptions alone.
Loading
Loading