docs: Add Claude Code proofing skill for specification quality checks #2252
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 <[email protected]>
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 373da35 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
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 <[email protected]>
|
I tried this out and had to change the file structure a little to conform to claude-code spec (running claude-code locally or in a container, I did not try the claude-code webui). yarikoptic#1 |
asmacdo
reviewed
Nov 11, 2025
Comment on lines
+15
to
+46
| ## 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 <file> --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 | ||
|
|
There was a problem hiding this comment.
IMO this should be pulled from this skill and put into CLAUDE.md
asmacdo
reviewed
Nov 11, 2025
|
|
||
| # Run schema tests | ||
| pytest tools/schemacode/ | ||
| ``` |
There was a problem hiding this comment.
IMO this should be pulled from this skill, and placed in the CONTRIBUTING.md
Probably CLAUDE.md should reference CONTRIBUTING.md, maybe the skill should also? (Not sure if redundancy would be helpful)
Fixup claude skill
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #2252 +/- ##
=======================================
Coverage 82.83% 82.83%
=======================================
Files 20 20
Lines 1672 1672
=======================================
Hits 1385 1385
Misses 287 287 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
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:
Files modified:
🤖 Generated with Claude Code
This a draft and not sure if should be merged... found only a few gotchas (I will send a PR separate) and not entirely turnkey.. May be with smth like https://github.com/con/yolo (attn @asmacdo to may be give a shot)