# Justfile Style

> Style guidelines for justfile recipe documentation. Use when writing or editing justfiles to ensure consistent and concise documentation. Use when this capability is needed.

- Skill: `tomevault-io/justfile-style` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/justfile-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/justfile-style/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/justfile-style

---


# Justfile Style Guidelines

This skill provides best practices for writing justfile recipe documentation comments.

## Doc Comment Simplification

For very short justfile recipes, change the doc comment string to be the entire command instead of a descriptive phrase.

### When to Simplify

- The cutoff for when to perform this refactoring should be approximately a single line of 120 characters
- If the recipe is a shebang recipe, don't shorten the doc comment
- If the recipe is multiple lines, or longer than 120 characters, don't shorten the doc comment

### Example Transformation

❌ Before:

```justfile
# Install dependencies
[group('setup')]
install:
    npm install
```

✅ After:

```justfile
# npm install
[group('setup')]
install:
    npm install
```

### Rationale

For simple, single-command recipes, the command itself is often more informative than a descriptive phrase. This approach:

1. **Reduces redundancy**: "Install dependencies" vs "npm install" convey the same information
2. **Shows the actual command**: Users can see exactly what will run
3. **Maintains consistency**: All simple recipes follow the same pattern
4. **Improves scannability**: The actual command is immediately visible

### When NOT to Simplify

Keep descriptive doc comments for:

1. **Multi-line recipes**:

```justfile
# Set up development environment
[group('setup')]
dev-setup:
    npm install
    cp .env.example .env
    just db-migrate
```

2. **Shebang recipes**:

```justfile
# Generate API documentation
[group('docs')]
gen-docs:
    #!/usr/bin/env bash
    set -euo pipefail
    # ... multiple lines of bash script
```

3. **Long single-line commands** (>120 characters):

```justfile
# Build production bundle with optimizations
[group('build')]
build-prod:
    webpack --mode production --config webpack.prod.js --optimization-minimize --output-path dist/
```

In these cases, a descriptive comment provides more value than repeating the complex command.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/motlin) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->