From 8571e1b3225da0f83d1d7ee461f2230e3f0fa573 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 12 May 2026 12:37:22 +0200
Subject: [PATCH] agents: hoist lint.sh to scripts/ for cross-skill use

The lint script was buried in the write skill's scripts directory, so
only agents that invoked that specific skill discovered it. Move it to
the repo-level scripts/ directory and reference it from AGENTS.md so
every agent session sees the recommended workflow.

- scripts/lint.sh: scoped markdownlint + vale on changed files
- AGENTS.md Commands and Verification loop now point here
- write skill SKILL.md updated to use the new path
- post-edit.sh stays in the skill (it's a PostToolUse hook tied to that
  skill's lifecycle)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .agents/skills/write/SKILL.md                     |  2 +-
 AGENTS.md                                         | 12 +++++++++++-
 {.agents/skills/write/scripts => scripts}/lint.sh |  6 +++---
 3 files changed, 15 insertions(+), 5 deletions(-)
 rename {.agents/skills/write/scripts => scripts}/lint.sh (63%)

diff --git a/.agents/skills/write/SKILL.md b/.agents/skills/write/SKILL.md
index 24f11e2b34..672a6ce0f4 100644
--- a/.agents/skills/write/SKILL.md
+++ b/.agents/skills/write/SKILL.md
@@ -45,7 +45,7 @@ Prettier runs automatically after each edit via the PostToolUse hook.
 Run lint manually after all edits are complete:
 
 ```bash
-${CLAUDE_SKILL_DIR}/scripts/lint.sh <changed-files>
+scripts/lint.sh <changed-files>
 ```
 
 The lint script runs markdownlint and vale on only the files you pass it,
diff --git a/AGENTS.md b/AGENTS.md
index 59f34cec9c..a315461cd2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -130,12 +130,17 @@ produces broken HTML — always check COMPONENTS.md for correct syntax.
 
 ```sh
 npx prettier --write <file>        # Format before committing
+scripts/lint.sh <file>...          # Lint specific files (markdownlint + vale)
 docker buildx bake validate        # Run all validation checks
 docker buildx bake lint            # Markdown linting only
 docker buildx bake vale            # Style guide checks only
 docker buildx bake test            # HTML and link checking
 ```
 
+For incremental work, prefer `scripts/lint.sh` over the `bake` targets —
+it runs the same checks on just the files you pass, so the output stays
+scoped to your changes instead of the whole repo.
+
 ### Validation in git worktrees
 
 `docker buildx bake validate` fails in git worktrees because Hugo cannot
@@ -147,9 +152,14 @@ and `validate-vendor` targets run correctly in CI.
 
 1. Make changes
 2. Format with prettier: `npx prettier --write <file>`
-3. Run `docker buildx bake lint vale`
+3. Lint the changed files: `scripts/lint.sh <file>...`
 4. Run a full build with `docker buildx bake` (optional for small changes)
 
+Always lint the specific files you changed before committing. Use
+`scripts/lint.sh` rather than the `bake` targets so the output is scoped
+to your changes — bake runs across the entire repo and the noise makes
+real issues easy to miss.
+
 ## Git hygiene
 
 - **Stage files explicitly.** Never use `git add .` / `git add -A` /
diff --git a/.agents/skills/write/scripts/lint.sh b/scripts/lint.sh
similarity index 63%
rename from .agents/skills/write/scripts/lint.sh
rename to scripts/lint.sh
index 4ccb1fd202..ab49f01be4 100755
--- a/.agents/skills/write/scripts/lint.sh
+++ b/scripts/lint.sh
@@ -1,9 +1,9 @@
 #!/bin/bash
 # Run markdownlint and vale on specific files.
-# Usage: .agents/skills/write/scripts/lint.sh <file> [file...]
+# Usage: scripts/lint.sh <file> [file...]
 #
-# Designed for agent workflows — scoped output, no repo-wide noise.
-# For full repo validation, use: docker buildx bake validate
+# Scoped output — no repo-wide noise. For full repo validation, use:
+#   docker buildx bake validate
 set -uo pipefail
 
 if [ $# -eq 0 ]; then