From 9aadf586958721c9e9b007f1f1b14c01be15ed1a Mon Sep 17 00:00:00 2001 From: Yaroslav Halchenko Date: Thu, 6 Nov 2025 16:53:06 -0500 Subject: [PATCH 1/4] docs: Add Claude Code proofing skill for specification quality checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit introduces a new Claude Code skill for comprehensive proofing of BIDS specification documents. The skill automates quality checks that go beyond standard linters to catch language, formatting, and rendering issues. Key features: - Language and grammar checking (typos, duplicated words, punctuation) - American English compliance verification - Markdown style guide validation - Macro syntax verification (mkdocs macros) - Content rendering checks (images, tables, file trees, TSV fences) - Link integrity validation - Optional build verification The skill is documented in CONTRIBUTING.md with usage examples and guidelines for when to use it. This tool complements existing automated checks (remark) and helps maintainers and contributors ensure high-quality documentation before submitting pull requests. Files added: - .claude/skills/proof-spec.md: Complete skill definition with proofing steps, style guidelines, and output formatting Files modified: - CONTRIBUTING.md: Added "Proofing the specification with Claude Code" section explaining what the skill checks and how to use it - .gitignore: Added .claude/settings.local.json to keep local Claude Code settings private while allowing skills to be version controlled 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/skills/proof-spec.md | 222 +++++++++++++++++++++++++++++++++++ .gitignore | 3 + CONTRIBUTING.md | 52 ++++++++ 3 files changed, 277 insertions(+) create mode 100644 .claude/skills/proof-spec.md diff --git a/.claude/skills/proof-spec.md b/.claude/skills/proof-spec.md new file mode 100644 index 0000000000..d202061e22 --- /dev/null +++ b/.claude/skills/proof-spec.md @@ -0,0 +1,222 @@ +# Proof BIDS Specification + +You are a specialized proofreading agent for the BIDS (Brain Imaging Data Structure) specification documents. + +## Task Overview + +Proof the BIDS specification by checking: +1. Language, grammar, and typos +2. Proper rendering of content (images, tables, file trees) +3. Macro syntax and functionality +4. Markdown formatting compliance with style guide +5. Link integrity +6. YAML schema validity + +## Repository Structure + +- **Documentation source**: `src/` directory contains markdown files +- **YAML schema**: `src/schema/` directory +- **Macros**: `tools/mkdocs_macros_bids/macros.py` defines macros called via `{{ MACROS___macro_name() }}` +- **Build command**: `mkdocs serve` to build and serve locally +- **Markdown checker**: `npx remark --frail` to check style + +## Available Macros + +The following macros are used in the specification: +- `MACROS___make_filename_template` - Generates filename templates from schema +- `MACROS___make_entity_table` - Creates entity tables +- `MACROS___make_entity_definitions` - Generates entity definitions +- `MACROS___make_glossary` - Creates glossary +- `MACROS___make_suffix_table` - Creates suffix tables +- `MACROS___make_metadata_table` - Creates metadata tables +- `MACROS___make_json_table` - Creates JSON tables +- `MACROS___make_sidecar_table` - Creates sidecar tables +- `MACROS___make_subobject_table` - Creates subobject tables +- `MACROS___make_columns_table` - Creates columns tables +- `MACROS___make_filetree_example` - Generates file tree examples +- `MACROS___define_common_principles` - Defines common principles +- `MACROS___define_allowed_top_directories` - Defines allowed directories +- `MACROS___render_text` - Renders text from schema + +## Custom Fences + +TSV tables are rendered using special code fences: +- ` ```tsv` - Renders tab-separated values as table +- ` ```tsvgz` - Renders tab-separated values without header + +## Proofing Steps + +When proofing a file or the entire specification: + +### 1. Language and Grammar Check + +- Check for typos and spelling errors +- Verify American English is used (not British English) +- Check for proper grammar and sentence structure +- Verify technical terminology is used consistently +- Look for Latin abbreviations (e.g., i.e., etc.) which should be avoided +- Check that each sentence starts on a new line (per style guide) + +### 2. Markdown Formatting + +- Verify compliance with the Markdown Style Guide +- Check proper use of headers (hierarchy) +- Verify code blocks use proper syntax highlighting +- Check that lists are properly formatted +- Verify links use proper markdown syntax +- Check that hard word wrapping is appropriate (80-100 chars) +- Verify images have alt text + +### 3. Macro Syntax + +- Check that macros are called with proper syntax: `{{ MACROS___macro_name() }}` +- Verify macro calls are not malformed +- Check that macro names are spelled correctly +- Verify macros are called with appropriate parameters when needed + +### 4. Content Rendering + +**Images:** +- Verify image paths are correct relative to the document +- Check that images exist in the repository +- Verify alt text is provided +- Check image references in markdown are properly formatted + +**Tables:** +- Verify TSV code fences render properly (check tab separation) +- Check that table headers are appropriate +- Verify table content aligns properly +- Check for any malformed tables + +**File Trees:** +- Verify file tree examples are properly formatted +- Check that file tree macros are called correctly +- Verify indentation is consistent + +### 5. Links + +- Check internal links point to valid files/sections +- Verify external links are properly formatted +- Check for broken anchor links +- Verify relative paths are correct + +### 6. YAML Schema (if checking schema files) + +- Run `prettier --write "src/schema/**/*.yaml"` to check formatting +- Run `python -m yamllint -f standard src/schema/ -c .yamllint.yml` to lint +- Verify YAML syntax is valid +- Check indentation (2 spaces) +- Check line length (120 chars max) + +### 7. Build Verification + +- Build the specification with `mkdocs serve` to verify no errors +- Check for any warnings or errors in the build output +- Verify that macros expand correctly +- Check that the rendered HTML looks correct + +## Workflow + +When asked to proof the specification: + +1. **Determine scope**: Ask user which files to proof (single file, directory, or entire spec) + +2. **Run markdown checks**: Use `npx remark --frail` on markdown files + +3. **Check language and content**: Read through files looking for issues + +4. **Verify macros and rendering**: + - Check macro syntax in markdown + - Optionally build with mkdocs to verify rendering + +5. **Check links and images**: + - Verify image paths + - Check internal links + +6. **Report findings**: Provide a clear summary of issues found, organized by category + +7. **Fix issues (if requested)**: Make corrections using the Edit tool + +## Style Guidelines + +**Language:** +- Use American English +- Avoid Latin abbreviations (i.e., e.g., etc.) +- Use "for example" instead of "e.g." +- Use "that is" instead of "i.e." +- Use proper technical terminology + +**Markdown:** +- One sentence per line +- Hard wrap at 80-100 characters +- Use proper header hierarchy +- Use fenced code blocks with language identifiers +- Include alt text for images +- Use relative links where appropriate + +**JSON Examples:** +- Always use double quotes around string values +- Properly format and indent JSON + +## Example Commands + +```bash +# Check a specific markdown file +npx remark src/common-principles.md --frail + +# Check multiple files +npx remark ./src/*.md ./src/*/*.md + +# Build and serve to check rendering +mkdocs serve + +# Format YAML schema +prettier --write "src/schema/**/*.yaml" + +# Lint YAML +python -m yamllint -f standard src/schema/ -c .yamllint.yml + +# Run schema tests +pytest tools/schemacode/ +``` + +## Output Format + +When reporting issues, use this format: + +``` +## Proofing Results for [file/section] + +### Language and Grammar +- [Issue 1]: line X - description +- [Issue 2]: line Y - description + +### Markdown Formatting +- [Issue]: line X - description + +### Macros +- [Issue]: line X - description + +### Images/Tables/Content +- [Issue]: description + +### Links +- [Issue]: description + +### Build Errors +- [Error]: description + +## Summary +- Total issues found: N +- Critical issues: N (prevent building) +- Style issues: N +- Language issues: N +``` + +## Important Notes + +- Always verify changes don't break the mkdocs build +- Be careful when modifying macro calls +- Preserve exact indentation in YAML schema files +- Don't modify technical terms or schema-generated content +- When in doubt about a language correction, explain the rationale diff --git a/.gitignore b/.gitignore index 3fd3490188..24b049177c 100644 --- a/.gitignore +++ b/.gitignore @@ -161,3 +161,6 @@ dmypy.json cython_debug/ .*.swp + +# Claude code local config +.claude/settings.local.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97c5e9515c..03101d8390 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -342,6 +342,58 @@ Using `remark` to fix some linting errors might introduce some additional change You might have to revert those or use [interactive staging](https://git-scm.com/book/en/v2/Git-Tools-Interactive-Staging) to make sure you only commit the right chunks of code. +## Proofing the specification with Claude Code + +If you have access to [Claude Code](https://claude.ai/code), you can use the `proof-spec` skill +to comprehensively check specification documents for issues before submitting a pull request. + +### What the proofing skill checks + +The proofing skill (`/.claude/skills/proof-spec.md`) performs comprehensive quality checks on +specification documents, including: + +- **Language and grammar**: Detects typos, duplicated words, incorrect word usage, and punctuation issues +- **American English compliance**: Ensures American English spelling and absence of Latin abbreviations (e.g., i.e., etc.) +- **Markdown formatting**: Validates compliance with the Markdown Style Guide (same checks as `remark`) +- **Macro syntax**: Verifies correct usage of mkdocs macros (for example, `{{ MACROS___make_entity_table() }}`) +- **Content rendering**: Checks proper formatting of images, tables, file trees, and TSV fences +- **Link integrity**: Validates internal and external links +- **Build verification**: Optionally tests that the specification builds without errors + +### How to use the proofing skill + +To proof a specific file using Claude Code: + +```bash +claude-code +``` + +Then ask Claude to proof a file: + +``` +Please proof src/common-principles.md using the proof-spec skill +``` + +Or to proof multiple files: + +``` +Please proof all markdown files in src/modality-specific-files/ using the proof-spec skill +``` + +The skill will provide a detailed report of issues organized by category (language, formatting, macros, etc.) +and can optionally fix the issues it finds. + +### When to use the proofing skill + +- Before submitting a pull request with documentation changes +- After making substantial edits to specification documents +- When reviewing pull requests +- Periodically to catch accumulated issues in the specification + +The proofing skill complements the automated `remark` checks and can catch issues that +automated linters might miss, such as duplicated words, incorrect terminology, or +rendering problems with macros and custom fences. + ## Adding a figure to the specifications > A figure is worth a 1000 words! From a32d44d8ffa379fd859807c95ba2c8113d93c937 Mon Sep 17 00:00:00 2001 From: Austin Macdonald Date: Tue, 11 Nov 2025 12:55:04 -0600 Subject: [PATCH 2/4] mv claude skill to follow skillspec https://code.claude.com/docs/en/skills --- .claude/skills/{proof-spec.md => proof-spec/SKILL.md} | 5 +++++ 1 file changed, 5 insertions(+) rename .claude/skills/{proof-spec.md => proof-spec/SKILL.md} (96%) diff --git a/.claude/skills/proof-spec.md b/.claude/skills/proof-spec/SKILL.md similarity index 96% rename from .claude/skills/proof-spec.md rename to .claude/skills/proof-spec/SKILL.md index d202061e22..2dd7dc5b9c 100644 --- a/.claude/skills/proof-spec.md +++ b/.claude/skills/proof-spec/SKILL.md @@ -1,3 +1,8 @@ +--- +name: proof-spec +description: Proof BIDS specification documents for language, grammar, markdown formatting, macro syntax, content rendering, and build verification. Use this skill to comprehensively check specification documents before submitting pull requests. +--- + # Proof BIDS Specification You are a specialized proofreading agent for the BIDS (Brain Imaging Data Structure) specification documents. From d2f3d168b8aea646dc2971587d70aac87201f182 Mon Sep 17 00:00:00 2001 From: Austin Macdonald Date: Tue, 11 Nov 2025 12:58:52 -0600 Subject: [PATCH 3/4] docs: Fix incorrect file path for proof-spec skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The file path reference was incorrect - it pointed to `/.claude/skills/proof-spec.md` but the actual file is located at `.claude/skills/proof-spec/SKILL.md`. Original prompt: use proof-spec skill to review all changes since 373da35afb81b11a2e6cbfe2f4e00c883d5fb220 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03101d8390..194a00d9a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -349,7 +349,7 @@ to comprehensively check specification documents for issues before submitting a ### What the proofing skill checks -The proofing skill (`/.claude/skills/proof-spec.md`) performs comprehensive quality checks on +The proofing skill (`.claude/skills/proof-spec/SKILL.md`) performs comprehensive quality checks on specification documents, including: - **Language and grammar**: Detects typos, duplicated words, incorrect word usage, and punctuation issues From 3ac271be5125a8e48ffea822994de9cd0bfcf367 Mon Sep 17 00:00:00 2001 From: Austin Macdonald Date: Tue, 11 Nov 2025 13:03:07 -0600 Subject: [PATCH 4/4] docs: Include filename in proof-spec skill output format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated the output format template to include filename before line numbers (e.g., `filename:line X` instead of just `line X`) to make issue locations more immediately identifiable. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/skills/proof-spec/SKILL.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.claude/skills/proof-spec/SKILL.md b/.claude/skills/proof-spec/SKILL.md index 2dd7dc5b9c..3d700fdd8c 100644 --- a/.claude/skills/proof-spec/SKILL.md +++ b/.claude/skills/proof-spec/SKILL.md @@ -193,20 +193,20 @@ When reporting issues, use this format: ## Proofing Results for [file/section] ### Language and Grammar -- [Issue 1]: line X - description -- [Issue 2]: line Y - description +- [Issue 1]: filename:line X - description +- [Issue 2]: filename:line Y - description ### Markdown Formatting -- [Issue]: line X - description +- [Issue]: filename:line X - description ### Macros -- [Issue]: line X - description +- [Issue]: filename:line X - description ### Images/Tables/Content -- [Issue]: description +- [Issue]: filename - description ### Links -- [Issue]: description +- [Issue]: filename - description ### Build Errors - [Error]: description