Streamline vale usage in docs-review skill - #7779
Conversation
Signed-off-by: Kim Nylander <kim.nylander@grafana.com>
There was a problem hiding this comment.
Pull request overview
This PR streamlines the docs-review skill’s use of Vale by introducing a wrapper script that emits a more compact, token-efficient summary of Vale findings, and updates the skill documentation to use that wrapper.
Changes:
- Add
.claude/skills/shared/vale-compact.shto compact Vale output via JSON +jq, plus a short summary by check. - Update the docs-review skill instructions to run the new wrapper script instead of invoking
valedirectly.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
.claude/skills/shared/vale-compact.sh |
New helper script that runs Vale in JSON mode and compacts findings to reduce repeated boilerplate. |
.claude/skills/docs-review/SKILL.md |
Updates the docs-review workflow to use the new compact Vale wrapper. |
Suppressed comments (1)
.claude/skills/shared/vale-compact.sh:28
- MEDIUM: Using
echo "$json"to feed JSON intojqcan be lossy/ambiguous (e.g., someechoimplementations interpret escapes or-n).printf '%s\n' "$json"is safer for passing through exact JSON bytes.
echo "$json" | jq -r '
to_entries[] as $f
| $f.value[] as $a
| [$f.key, ($a.Line|tostring), ($a.Span[0]|tostring), $a.Severity, $a.Check, $a.Match] | @tsv
' | sort -t $'\t' -k1,1 -k2,2n | awk -F'\t' '{printf "%s:%s:%s\t%s\t%s\t%s\n",$1,$2,$3,$4,$5,$6}'
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| json="$(vale --output=JSON "$@" || true)" | ||
|
|
||
| if ! command -v jq >/dev/null 2>&1; then | ||
| echo "$json" | ||
| exit 0 | ||
| fi |
There was a problem hiding this comment.
nit: Grafana Labs does have a habit of using the .sh extension for Bash scripts but I'd prefer .bash to be clear
| fi | ||
| if [ "$#" -eq 0 ]; then | ||
| echo "usage: vale-compact.sh <file>..." >&2 | ||
| exit 1 |
There was a problem hiding this comment.
Nit: common to exit 2 on usage error
| echo "$json" | jq -r ' | ||
| to_entries[] as $f | ||
| | $f.value[] as $a | ||
| | [$f.key, ($a.Line|tostring), ($a.Span[0]|tostring), $a.Severity, $a.Check, $a.Match] | @tsv | ||
| ' | sort -t $'\t' -k1,1 -k2,2n | awk -F'\t' '{printf "%s:%s:%s\t%s\t%s\t%s\n",$1,$2,$3,$4,$5,$6}' |
There was a problem hiding this comment.
This depends on external sort and more awk-wardly (haha), it also relies on awk. To be most easily cross-platform, I'd probably ask your agent to have jq do all the sorting and output formatting. Perhaps surprisingly, I think that's actually more readable even though jq syntax can be annoyingly hard to inspect.
Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
Suppressed comments (1)
.claude/skills/shared/vale-compact.sh:17
- CRITICAL: This line also appears to have a CRLF (
)"\r). If the file is checked out with CRLFs, bash may fail to execute it. Normalize to LF line endings.
json="$(vale --no-exit --output=JSON "$@")"
| echo "vale not installed (https://vale.sh/docs/install/); check style manually." >&2 | ||
| exit 0 | ||
| fi | ||
| if [[ "$#" -eq 0 ]]; then |
Rename to .bash, fold sort/format into jq, and fall back to native vale when jq is missing.
|
|
||
| ```bash | ||
| vale <file_path> | ||
| .claude/skills/shared/vale-compact.bash <file_path> |
What this PR does:
Added a script to help with vale to help reduce token usage when using the docs-review skill.
Made with the help of Claude.
Which issue(s) this PR fixes:
Part of #7776
Checklist
.chloggen/(runmake chlog-new, ormake chlog-new FILENAME=<name>to override the default branch-name file; see.chloggen/README.md)