docs(lint): add docs index for Vale research docs

plugins/lint/docs/research/docs/vale/ had no top-level index pointing
into it, unlike plugins/kyberforge/docs/README.md which indexes its
own research directories. Add plugins/lint/docs/README.md mirroring
that convention: one line per file describing what it covers, plus a
provenance note tying the directory back to plugins/lint/sources.md
and the vale-config/vale-run skills that consume it.

Closes out a follow-up item from PR #85's review.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58

.claude-plugin/marketplace.json

@@ -38,7 +38,12 @@
         "repo": "mattpocock/skills",
         "source": "github"
       }
+    },
+    {
+      "description": "Skills and agents for configuring and running linters.",
+      "name": "lint",
+      "source": "./plugins/lint"
     }
   ],
-  "version": "0.2.0"
+  "version": "0.3.1"
 }

.github/plugin/marketplace.json

@@ -38,7 +38,12 @@
         "repo": "mattpocock/skills",
         "source": "github"
       }
+    },
+    {
+      "description": "Skills and agents for configuring and running linters.",
+      "name": "lint",
+      "source": "./plugins/lint"
     }
   ],
-  "version": "0.2.0"
+  "version": "0.3.1"
 }

.pre-commit-config.yaml

@@ -98,6 +98,24 @@ repos:
               fi
             done
 
+      - id: skill-size-check
+        stages: ['pre-commit']
+        name: SKILL.md size ceiling
+        description: Enforce agentskills.io's 500-line/5,000-token SKILL.md size ceiling
+        entry: scripts/skill-size-check.sh
+        language: script
+        files: '^plugins/[^/]+/skills/[^/]+/SKILL\.md$'
+        pass_filenames: true
+
+      - id: vale-audit-prefilter
+        stages: ['pre-commit']
+        name: Vale audit prefilter
+        description: Run Vale against skill/agent markdown files as a deterministic prefilter for skill-audit/agent-audit
+        entry: scripts/vale-wrap.sh --config .vale.ini --minAlertLevel=warning
+        language: script
+        files: '^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$'
+        pass_filenames: true
+
   - repo: meta
     hooks:
       - id: check-hooks-apply

.vale.ini

@@ -0,0 +1,11 @@
+StylesPath = styles
+MinAlertLevel = suggestion
+
+[plugins/*/skills/*/SKILL.md]
+BasedOnStyles = Kyberforge
+
+[plugins/*/agents/*.md]
+BasedOnStyles = Kyberforge
+
+[plugins/*/agents/*.agent.md]
+BasedOnStyles = Kyberforge, KyberforgeCopilot

AGENTS.md

@@ -10,6 +10,7 @@ This repo is the global AI development configuration repository — the authorit
 ## Setup
 
 - Install git hooks: `pre-commit install -t pre-commit -t pre-push -t commit-msg`. `.pre-commit-config.yaml` uses all three stages and has no `default_install_hook_types` set, so a plain `pre-commit install` only wires the `pre-commit` stage and silently skips `commit-msg` (Conventional Commits check) and `pre-push` (test suite, manifest check).
+- Install the `vale` binary — required by the `vale-audit-prefilter` pre-commit hook, which runs on every commit touching a `SKILL.md` or agent `.md` file. Without it, the hook fails with a bare "command not found" and no install pointer. Install via a package manager (`brew install vale` on macOS, `snap install vale` on Linux, `choco install vale` on Windows) or see https://vale.sh/docs/vale-cli/installation/; then run `vale sync` to pull the styles declared in `.vale.ini`.
 
 ## Testing instructions
 

CONTEXT.md

@@ -66,5 +66,15 @@ A skill pair in the `core` plugin for writing, updating, and reviewing a target
 ### provider-adapter-author
 A companion skill (`core` plugin) that detects a target repo's provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) and, where it duplicates content AGENTS.md should own, converts it into a thin adapter that imports AGENTS.md — mirroring this repo's own ADR-0002/ADR-0003 two-tier adapter pattern. Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`: checks for an import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — the check is mechanical, so a script suffices per governance.md's "prefer deterministic code for repeatable tasks." `agentsmd-author` calls this skill via skill composition when it detects an existing provider file with overlapping content.
 
+### lint plugin
+A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
+
+### Vale audit prefilter (skill-audit / agent-audit)
+Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so its config lives at the repo root rather than inside `plugins/lint/`: `.vale.ini` plus a custom `Kyberforge` style (`styles/Kyberforge/`) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style (`styles/KyberforgeCopilot/`) scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check. `error` alerts map to FAIL, `warning`/`suggestion` map to SUGGESTION. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, two body-wide prose-pattern checks (vague-qualifier filler, "There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
+
+Both skills' Step 1, and the `vale-audit-prefilter` pre-commit hook, call `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched. `tests/test-vale-wrap.sh` regression-tests this. Both call sites still scope every invocation to the specific file(s) being audited, never a repo-wide sweep — Vale's glob matching crosses directory boundaries (`plugins/*/agents/*.md` matches nested `docs/research/examples/**/agents/*.md` too), so scoping is what keeps research-example files out of the audit's lint pass. The pre-commit hook's own glob is tightened to `^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$` (single-segment, not `.*`) for the same reason, since pre-commit invokes it automatically against whatever staged files match rather than a manually-scoped target.
+
+This scope expands per ADR-0013: cherry-picked low-noise `write-good`/`alex` rules landed in `styles/Kyberforge` as two new rule files, `Kyberforge.VagueQualifier` and `Kyberforge.SentenceOpenerThereIs`, plus a new sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's 500-line/5,000-token `SKILL.md` ceiling — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter`, so it never lints `docs/research/examples/` reference skills. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine).
+
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.

docs/adr/0013-vale-harness-scope-and-rule-sources.md

@@ -0,0 +1,93 @@
+# Vale audit prefilter expands into a plugin-content harness, scoped to prose-pattern rules only
+
+Issue #84 wired Vale as a deterministic prefilter for `skill-audit`/`agent-audit`, scoped to
+exactly four pattern-matchable checks (imperative description opener, vague capability wording,
+generic reference-pointer padding, Copilot's dead `Use proactively` phrasing), documented only in
+CONTEXT.md's "Vale audit prefilter" section — never its own ADR — and explicitly excluding body
+discipline, near-miss exclusion strength, and control calibration as non-goals. This ADR records a
+deferred PR #85 review item to broaden that coverage, retroactively captures #84's own rationale
+(since it was never recorded as a decision in its own right), and layers the expansion on top
+without reversing or weakening the original four rules.
+
+**File scope stays the same.** `SKILL.md` plus agent files (`plugins/*/agents/*.md`,
+`plugins/*/agents/*.agent.md`) only — matching the existing prefilter's globs. Skill-level
+`README.md` files and `plugin.json` manifests are not added: README.md files are navigational, not
+spec-governed content, and `plugin.json` is JSON, not prose Vale can meaningfully lint.
+
+**Rule categories are prose-pattern-matchable only.** Structural, schema, and security concerns
+stay out of this Vale-based harness because this repo already has dedicated tools for them:
+`skill-frontmatter` (required frontmatter fields), `validate-plugins`/`validate-marketplace`
+(`claude plugin validate --strict`, schema), and `gitleaks`/`detect-private-key` (secrets).
+Duplicating those concerns as Vale rules would fight tools that already own them better.
+
+**Governance docs are excluded as a rule source.** `docs/research/governance_principles/CONTROLS.md`
+and `governance.md` were investigated and found to contribute nothing minable: CONTROLS.md is
+org/CI-infrastructure controls (secret scanning, dependency/license scanning, agent permission
+scoping, audit logging, human approval gates, periodic reviews) — none of it is a prose pattern
+expressible as a Vale rule against SKILL.md/agent-file text, and what it does cover is either
+already handled elsewhere (gitleaks) or genuinely out of scope for a plugin-content prose harness
+(dependency/license scanning is a code-dependency concern, not skill authoring).
+
+**Spec-derived custom rules stay mostly as-is.** Re-reading agentskills.io's
+`optimizing-descriptions.md` and `skill-authoring.md`, plus `claude-code-plugins/agent-definition.md`
+and `github-copilot-plugins/agent-definition.md`, found that the existing four Kyberforge rules
+already cover the pattern-matchable surface those specs describe. The remaining spec guidance —
+calibrating control vs. giving freedom, avoiding menus of options, coherent skill scope, moderate
+detail level — is semantic judgment, already `skill-audit`'s job via LLM review, not new lintable
+rules. One confirmation surfaced: Claude Code's `Use proactively` phrasing is meaningful for `.md`
+agent files (it triggers auto-invocation), unlike Copilot's `.agent.md` files where it's dead
+phrasing — so `KyberforgeCopilot/ProactivePhrase`'s existing `.agent.md`-only scope is correct and
+must not be extended to `.md` files.
+
+**`write-good`/`alex` are trialed, not adopted wholesale.** These built-in/third-party Vale
+packages are tuned for general blog-style prose (passive voice, weasel words, wordy phrases) and
+are expected to be noisy against this repo's terse, imperative instruction-file corpus. Only
+individual rules proven low-noise against the existing corpus get cherry-picked into
+`styles/Kyberforge`; the packages are never referenced wholesale in `BasedOnStyles`.
+
+**A new non-Vale check closes a real gap.** `skill-authoring.md` states `SKILL.md` should stay
+under 500 lines / 5,000 tokens — currently unenforced anywhere in this repo. This is a whole-file
+length ceiling, not a text pattern, so it isn't a Vale rule — it becomes a new deterministic script
+and pre-commit hook, sibling to the existing `skill-frontmatter` hook.
+
+**Rules land directly in `styles/Kyberforge`, enforcing immediately.** No trial/report-only tier
+is introduced (see Considered Options). The implementation pass finalizes the cherry-picked
+`write-good`/`alex` rules and any new spec-derived rule wording, runs the full set against the
+existing SKILL.md/agent-file corpus, fixes any resulting violations across that corpus, and lands
+the rule changes and the corpus fixes as one atomic commit — the same enforcement model as the
+original four rules, never a partial or opt-in state.
+
+## Considered options
+
+**Phased rollout via a separate trial style + config (rejected).** A `styles/KyberforgeTrial/`
+directory plus a parallel `.vale.trial.ini` (mirroring the root config's globs but with
+`BasedOnStyles = Kyberforge, KyberforgeTrial`) would let new rules be swept report-only via
+`lint-runner`/`vale-run` before promotion into the enforcing `styles/Kyberforge` + root
+`.vale.ini`. This was considered because `BasedOnStyles = Kyberforge` activates every rule file
+under that directory automatically — there's no partial/opt-in application within a style, so a
+rule dropped straight into `styles/Kyberforge` goes live in the blocking pre-commit hook
+immediately. Rejected in favor of finalizing rules directly and fixing violations via subagent
+before committing: simpler, no new trial-config machinery to build or maintain — at the cost of no
+standing report-only tier for future candidate rules.
+
+## Consequences
+
+- `styles/Kyberforge/` gained two new rule files, cherry-picked from `write-good`/`alex` as
+  low-noise against this repo's corpus: `VagueQualifier.yml` and `SentenceOpenerThereIs.yml`.
+- A new pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforces the
+  500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`.
+- `styles/KyberforgeTrial/` and `.vale.trial.ini` were deliberately not created — noted here so a
+  future reader doesn't wonder if a trial tier was forgotten.
+- The styles-portability question — whether `styles/` and `.vale.ini` should move into
+  `plugins/lint/` so the prefilter also works for repos that install `kyberforge@holocron` as an
+  external plugin, rather than living at this repo's root — was deliberately deferred, not fixed,
+  in this pass. This repo-root placement remains intentional: this ADR's "File scope stays the
+  same" framing is specific to Kyberforge's own authoring conventions in this repo, not a generic
+  `lint`-plugin feature. Portability is a known limitation, tracked for a separate future session,
+  not silently forgotten.
+
+**What this ADR's implementation pass did:** synced and trialed `write-good`/`alex` against the
+existing SKILL.md/agent-file corpus, cherry-picked the two low-noise rules above into
+`styles/Kyberforge`, wrote `scripts/skill-size-check.sh` and its pre-commit hook, fixed the
+resulting corpus violations, and landed the rule changes and corpus fixes as one atomic commit —
+matching the enforcement model described above (no partial or opt-in state).

plugins/bin/skills/caveman/SKILL.md

@@ -15,7 +15,12 @@ ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drif
 
 ## Rules
 
-Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+<!-- vale Kyberforge.VagueQualifier = NO -->
+<!-- vale Kyberforge.VagueWording = NO -->
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging.
+<!-- vale Kyberforge.VagueQualifier = YES -->
+<!-- vale Kyberforge.VagueWording = YES -->
+Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
 
 Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
 

plugins/bin/skills/prototype/SKILL.md

@@ -14,7 +14,7 @@ Identify which question is being answered — from the user's prompt, the surrou
 - **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
 - **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
 
-The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+The two branches produce fundamentally different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
 
 ## Rules that apply to both
 

plugins/gitea/skills/gitea-issues/SKILL.md

@@ -31,7 +31,7 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i
 
 ## Gotchas
 
-- **`list_issues` has no `type` or `milestones` parameter — despite `api-reference.md` documenting both.** The live MCP schema (re-verified via `ToolSearch` at authoring time — see `references/sources.md`) only accepts `owner`, `repo` (required), `state` (default `"all"`), `labels` (array of label *names*), `since`, `before` (ISO 8601), `page`, `per_page` (default 30). There is no way to filter issues-vs-PRs or by milestone through this tool. Since issues and PRs share one number space, `list_issues` results can include PR entries with no client-side filter to exclude them. If you need to know whether a specific number is a PR, call `issue_read method: "get"` and check `is_pull` — that field only appears on the single-item response, never in a list item. This exact drift (a prior skill trusted the research doc's `type` param and broke) is why this skill's reference files were re-verified live rather than copied from `api-reference.md`.
+- **`list_issues` has no `type` or `milestones` parameter — despite `api-reference.md` documenting both.** The live MCP schema (re-verified via `ToolSearch` at authoring time — see `references/sources.md`) only accepts `owner`, `repo` (required), `state` (default `"all"`), `labels` (array of label *names*), `since`, `before` (ISO 8601), `page`, `per_page` (default 30). This tool provides no way to filter issues-vs-PRs or by milestone. Since issues and PRs share one number space, `list_issues` results can include PR entries with no client-side filter to exclude them. If you need to know whether a specific number is a PR, call `issue_read method: "get"` and check `is_pull` — that field only appears on the single-item response, never in a list item. This exact drift (a prior skill trusted the research doc's `type` param and broke) is why this skill's reference files were re-verified live rather than copied from `api-reference.md`.
 - **`search_issues` does have a working `type` filter** (`"issues"` | `"pulls"`) — unlike `list_issues`. Its `labels` parameter is also shaped differently: a comma-separated string, not an array of names.
 - **Labels are numeric IDs on write, name strings on read.** `issue_write`'s `labels` parameter (used by `add_labels`/`replace_labels`) takes IDs. `list_issues`/`issue_read` return names. Never resolve this yourself — compose `gitea-labels-milestones` (see `references/enrichments.md`) to get IDs.
 - **Milestone on `issue_read` is `{id, title}`** — an object, not a bare string. This skill only ever needs the `id`. (The bare-title-string case only happens on the PR side, which is `gitea-prs`' problem, not this skill's.)
@@ -86,7 +86,7 @@ Call `issue_read method: "get_comments" owner: <owner> repo: <repo> issue_number
 
 ### close `<N>`
 
-Call `issue_write method: "update" owner: <owner> repo: <repo> issue_number: <N> state: "closed"`. There is no `method: "close"`.
+Call `issue_write method: "update" owner: <owner> repo: <repo> issue_number: <N> state: "closed"`. No `method: "close"` exists.
 
 ### comment `<N>`
 

plugins/gitea/skills/gitea-prs/SKILL.md

@@ -29,7 +29,7 @@ allowed-tools: mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp_
 
 - **Issues and PRs share one number space.** A number the user mentions (`#42`) might be an issue, not a PR — there is only one counter per repo. If you're not certain, call `pull_request_read method: "get"` and treat a 404 as "this number is an issue, not a PR" (or check `is_pull` on an `issue_read` response first if you already have one).
 - **`pull_request_read method: "get"` returns `review_scomments`, not `review_comments`.** Source-level typo in gitea-mcp v1.3.0. Never reference `review_comments` — it will always be undefined.
-- **`draft: true` on create prepends `"WIP:"` to the title.** There is no first-class draft field — Gitea implements draft PRs via title prefix. To un-draft, call `update` and pass the title without the `WIP:` prefix.
+- **`draft: true` on create prepends `"WIP:"` to the title.** Gitea has no first-class draft field — it implements draft PRs via title prefix. To un-draft, call `update` and pass the title without the `WIP:` prefix.
 - **Cross-repo fork PRs require `head` as `"fork-owner:branch-name"`.** A bare branch name causes Gitea to search the base repo for it and return 422. Same-repo PRs use a bare branch name.
 - **PR `milestone` is a bare title string, not `{id, title}`.** Unlike issues, you cannot recover a milestone's ID from a PR response. If you need the ID (e.g. to filter or to pass to another write), call into `gitea-labels-milestones` and match by title via `milestone_read method: "list"`.
 - **CI status and review/approval state are independent merge gates.** `get_status` only reports CI. Branch-protection rules (required approvals, requested-reviewer coverage, stale-approval handling) are enforced server-side by the merge call itself and will error if unmet — passing CI does not mean the merge will succeed.

plugins/gitea/skills/gitea-releases/SKILL.md

@@ -22,7 +22,7 @@ metadata:
 
 - **`delete_release` takes a numeric `id`, never a tag name.** `delete_tag` is the mirror opposite — it takes the `tag_name` string, never a numeric id. These two tools are asymmetric on purpose; passing a tag name to `delete_release` or a numeric id to `delete_tag` fails. Always resolve the numeric release id via `list_releases` or `get_release` first if you only have a tag name in hand.
 - **Deleting a release does not delete its tag.** They are separate destructive operations against separate resources — a release is a wrapper (title, notes, draft/prerelease flags, assets) around a tag, not the tag itself. If the intent is to remove both, call `delete_release` and `delete_tag` separately.
-- **`list_releases`/`list_tags` default to `per_page: 20`**, unlike most other gitea-mcp tools which default to 30. There is no auto-pagination in the MCP layer — to get a complete result set, loop `page` upward until a page returns fewer than `per_page` results.
+- **`list_releases`/`list_tags` default to `per_page: 20`**, unlike most other gitea-mcp tools which default to 30. The MCP layer does no auto-pagination — to get a complete result set, loop `page` upward until a page returns fewer than `per_page` results.
 - **`is_draft`/`is_pre_release` are explicit booleans the caller sets on `create_release` — never inferred from `tag_name`.** Note the input param is `is_draft`, which maps to the `draft` field on the *response* object (see Dispatch table below and `references/call-signatures.md`) — `draft` is never a valid input key. Practitioner convention (per the `tea` CLI) uses `-beta`/`-rc` suffixes for prereleases (e.g. `v2.0.0-beta.1`), but Gitea does not enforce or infer this from the tag string. If the user names a tag that looks like a prerelease, set `is_pre_release: true` explicitly rather than assuming the flag is redundant with the name.
 - **Tag names are conventionally semver, `v`-prefixed** (`v1.2.0`, `v2.0.0-beta.1`), but this is a practitioner convention, not a Gitea constraint — don't reject or rewrite a caller-supplied tag name that doesn't follow it.
 
@@ -47,6 +47,6 @@ metadata:
 - [ ] **Creating a release:** Call `create_release` directly with `tag_name` + `target` + `title` — Gitea is assumed to create the underlying tag automatically if `tag_name` doesn't already exist (this is plausible behavior inferred from the API shape, not directly confirmed in the research docs), so a separate `create_tag` call is only needed when you want to tag a commit without wrapping it in a release yet. Verify the tag exists afterward if this matters to the caller. Set `is_pre_release`/`is_draft` explicitly per the Gotchas above; don't leave them to default inference.
 - [ ] **Deleting a release safely:** Resolve the numeric id first — call `list_releases` (paginate if needed, see Gotchas) or `get_release` if the id is already known, find the entry matching the target `tag_name`, then call `delete_release` with that `id`. Never pass `tag_name` to `delete_release`.
 - [ ] **Deleting a tag along with its release:** Delete the release first (frees the id lookup), then call `delete_tag` with the `tag_name` separately — confirm both are intended before proceeding, since each is an independent irreversible operation.
-- [ ] **Listing completely:** If the caller needs all releases or tags (not just the first page), loop `page: 1, 2, 3...` until a response has fewer than `per_page` entries.
+- [ ] **Listing every page:** If the caller needs all releases or tags (not just the first page), loop `page: 1, 2, 3...` until a response has fewer than `per_page` entries.
 
 If exact response field shapes or additional conventions are needed, read `references/call-signatures.md` and `references/conventions.md`.

plugins/kyberforge/skills/agent-audit/SKILL.md

@@ -36,10 +36,13 @@ metadata:
 ```bash
 bash scripts/validate.sh <path-to-agent-file>
 bash scripts/validate-provenance.sh <path-to-agent-file>
+"$(git rev-parse --show-toplevel)/scripts/vale-wrap.sh" --config "$(git rev-parse --show-toplevel)/.vale.ini" <path-to-cc-file> <path-to-copilot-file>
 ```
 
 The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, plugin-silently-ignored fields, body length, or subagent-unavailable tools → `### Provider safety`. A missing counterpart file → `### Pair consistency`.
 
+`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`, so it runs correctly regardless of the caller's cwd. Run it against both files of the pair (not just the one passed in). `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in the `### Description` / `### Body` dimensions, citing the rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if vale or `.vale.ini` is unavailable.
+
 `validate-provenance.sh` validates the provenance chain between the agent pair's `source_keys` and the plugin-scoped `sources.md` (plugin root — see ADR-0010). It exits 0 silently for non-plugin-scope agents and when no provenance data exists. Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
 
 If the scripts cannot run (Bash denied, python3 unavailable), perform checks manually: counterpart file exists, required fields present (`name`, `description`, non-empty body), `name` is kebab-case, Copilot CLI `.agent.md` `name` must match filename stem (CC files are exempt — the CC platform does not require name to match filename), no `FILL IN:` placeholders, no CC-only fields in Copilot file, no Copilot-only fields in CC file (read `references/field-inventory.md` for the authoritative field lists).
@@ -49,15 +52,17 @@ If the scripts cannot run (Bash denied, python3 unavailable), perform checks man
 Read both agent files. Work through each dimension internally. Collect findings only; report in Step 3.
 
 **Description (both files):**
-- Action-verb opening: description starts with a verb ("Reviews...", "Analyzes...", "Generates...") — FAIL if absent
-- Specificity: is the trigger condition stated precisely? — SUGGESTION if vague
-- `Use proactively` in a Copilot description: CC-specific phrasing, has no effect in Copilot — SUGGESTION to remove
+- Action-verb opening: description starts with a verb ("Reviews...", "Analyzes...", "Generates...") — FAIL if absent. Vale's `Kyberforge.DescriptionOpener` alert flags the specific known-bad "This agent..." opener directly; verifying an arbitrary opening word is genuinely a strong verb still requires judgment.
+- Specificity: is the trigger condition stated precisely? — SUGGESTION if vague. Vale's `Kyberforge.VagueWording` alert covers known filler ("helps with", "utilize", ...) directly; report those without re-deriving by judgment.
+- `Use proactively` in a Copilot description: Vale's `KyberforgeCopilot.ProactivePhrase` alert (Copilot file only) flags this directly — report it without re-deriving by judgment.
 
 If a description finding is borderline, read `references/description-quality.md`.
 
 **Body:**
 - Direct role instruction: system prompt opens with `You are a [role]. When invoked, [action].` — SUGGESTION if absent
 - One job per agent: system prompt describes a single bounded task — SUGGESTION if scope appears unbounded
+- Generic, non-specific reference pointers to the `references/` directory: Vale's `Kyberforge.PaddingPhrase` alert flags this directly — report it without re-deriving by judgment
+- Vague filler wording and sentences that open with "There is"/"There are": Vale's `Kyberforge.VagueQualifier` and `Kyberforge.SentenceOpenerThereIs` alerts flag this directly — report them without re-deriving by judgment
 
 **Body/Frontmatter comments:**
 - Inspect each comment block in the YAML frontmatter. For each comment, apply: *"Would the agent get this wrong without this comment?"* Flag any that answer "no" as padding.

plugins/kyberforge/skills/agent-author/SKILL.md

@@ -123,7 +123,7 @@ source_keys:
 
 ### Step 3 — Fill in the Copilot agent file
 
-There are **two distinct Copilot agent formats** with different paths and field sets. Choose one based on the deployment target:
+**Two distinct Copilot agent formats** exist, with different paths and field sets. Choose one based on the deployment target:
 
 **CLI format** (default — what the scaffold creates):
 - Path: `.github/agents/<name>.agent.md` (project) or `<plugin>/agents/<name>.agent.md` (plugin)

plugins/kyberforge/skills/skill-audit/SKILL.md

@@ -34,12 +34,15 @@ metadata:
 ```bash
 bash scripts/validate.sh <skill-dir>
 bash scripts/validate-provenance.sh <skill-dir>
+"$(git rev-parse --show-toplevel)/scripts/vale-wrap.sh" --config "$(git rev-parse --show-toplevel)/.vale.ini" <skill-dir>/SKILL.md
 ```
 
 Note any structural FAILs — they will appear in the report as a `### Structure` dimension. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts.
 
 Note any Provenance FAILs and INFO findings from `validate-provenance.sh` — they surface in the report as a `### Provenance` dimension (separate from `### Structure`). The script embeds full FAIL/INFO format with Why and Fix per finding; surface them verbatim.
 
+`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`, so it runs correctly regardless of the caller's cwd, using `.vale.ini`'s `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns dimensions below, not a replacement for Step 3. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in those dimensions, citing the rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if vale or `.vale.ini` is unavailable.
+
 ## Step 2 — Read all skill files
 
 Read every file in the skill directory: `SKILL.md`, `README.md` (if present), all files in `scripts/`, `references/`, `assets/`, and `tests/`. Skip binary files only. Do not skip text files — internal consistency checks require the full picture.
@@ -50,8 +53,9 @@ Work through each dimension internally. Collect findings only; report them in St
 
 ### Description
 
-- **Imperative phrasing**: does it use "Use when..." not "This skill..."?
-- **Specificity**: are capabilities stated precisely ("parses OpenAPI specs") or vaguely ("helps with APIs")?
+Vale's `Kyberforge.DescriptionOpener` (FAIL — "This skill..." openers) and `Kyberforge.VagueWording` (SUGGESTION — filler like "helps with", "utilize") alerts from Step 1 cover imperative phrasing and known vague-wording filler directly; report them as findings without re-deriving by judgment. The rest is still a judgment call:
+
+- **Specificity beyond the filler blocklist**: are capabilities stated precisely ("parses OpenAPI specs") or genuinely vaguely ("handles files")?
 - **Indirect triggers**: does it cover cases where the user doesn't name the domain directly?
 - **Near-miss exclusions**: are "Do not use when..." clauses present if a near-miss skill could steal activations?
 - **Length**: under 1024 characters?
@@ -66,6 +70,8 @@ For each sentence in the body, apply: *"Would the agent get this wrong without t
 - **Why rationale**: include/exclude rules explain why, not just what
 - **Control calibration**: prescriptive for fragile or critical sequences (e.g. a script invocation where flag order or exact arguments must not change); flexible where multiple approaches are valid
 
+Vale's `Kyberforge.VagueQualifier` (SUGGESTION — vague filler like "clearly", "obviously") and `Kyberforge.SentenceOpenerThereIs` (SUGGESTION — sentences starting with "There is"/"There are") alerts from Step 1 cover pattern-matchable body-wide filler directly; report them as findings without re-deriving by judgment.
+
 If uncertain whether a sentence is padding or whether a control decision is correctly calibrated, read `references/body-discipline.md`.
 
 ### Patterns
@@ -75,7 +81,7 @@ Check each pattern is appropriate and correctly formed:
 - **Gotchas**: placed near the top; each entry is a specific fact that defies a reasonable assumption — not a general tip
 - **Prescriptive sequence**: inner code fences escaped as `\`\`\`` when nested inside a markdown block
 - **Checklists**: used for multi-step workflows, not single steps
-- **Conditional references**: specific trigger stated ("If X, read `references/file.md`") — not a generic "see references/"
+- **Conditional references**: specific trigger stated ("If X, read `references/file.md`") — not a generic "see references/". Vale's `Kyberforge.PaddingPhrase` alert from Step 1 flags the generic phrasing directly; other malformed conditional-reference forms still require judgment.
 - **Output templates**: present when the agent must produce a specific format; absent otherwise
 
 ### File structure

plugins/lint/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "author": {
+    "name": "Defame1297",
+    "url": "https://git.dev.rkdr.net/Defame1297/"
+  },
+  "description": "Skills and agents for configuring and running linters.",
+  "displayName": "Lint",
+  "keywords": [
+    "lint",
+    "style",
+    "prose",
+    "linter"
+  ],
+  "license": "MIT",
+  "name": "lint",
+  "version": "1.1.2"
+}

plugins/lint/.mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

plugins/lint/agents/lint-runner.agent.md

@@ -0,0 +1,41 @@
+---
+name: lint-runner
+
+description: Runs a linter sweep over a target file or directory scope and reports findings. Currently backs onto Vale (prose/style linting) via the vale-config and vale-run skills; built to add other linters later without changing its own contract. Use when a caller needs a lint pass run in an isolated context and wants findings back, not fixes applied.
+
+tools: ["execute", "read", "search"]
+
+source_keys:
+  - context7-websites-vale-sh
+
+---
+
+You are a linter runner. When invoked, you run the appropriate linter(s) over the requested scope, collect their findings, and report them back in a structured, reviewable form. You never edit files.
+
+## Inputs
+
+- **scope:** file path, directory path, or glob to lint
+- **linter:** which linter to run (defaults to `vale` — the only backend currently wired up)
+- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini` for Vale, or whatever config format the requested linter expects); if none exists, say so in your report rather than inventing one
+
+## Process
+
+1. Determine whether the target scope already has configuration in place for the requested `linter` (whatever config format that linter expects). If not, use the `<linter>-config` skill (e.g. `vale-config` when `linter` is `vale`) to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
+2. Use the `<linter>-run` skill (e.g. `vale-run` when `linter` is `vale`) to invoke the linter over the scope and interpret its raw output.
+3. Normalize findings into one shape regardless of backend linter: file, line, rule/check, severity, message.
+4. Do not edit, fix, or rewrite any flagged content. If a finding looks trivially fixable, note that in the report — do not act on it.
+5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), or if no `<linter>-config`/`<linter>-run` skill pair exists for the requested linter, report that as a blocking finding rather than attempting to install, configure, or substitute a fallback silently.
+
+## Output
+
+Report findings as a flat list, most-severe first:
+
+```
+- file: <path>
+  line: <line number or range>
+  rule: <check/rule name>
+  severity: <error | warning | suggestion>
+  message: <finding text>
+```
+
+Follow with a one-line summary: total findings by severity, and whether the run was blocked (e.g. linter not configured). If there are zero findings, say so explicitly — do not omit the report.

plugins/lint/agents/lint-runner.md

@@ -0,0 +1,41 @@
+---
+name: lint-runner
+
+description: Runs a linter sweep over a target file or directory scope and reports findings. Currently backs onto Vale (prose/style linting) via the vale-config and vale-run skills; built to add other linters later without changing its own contract. Use when a caller needs a lint pass run in an isolated context and wants findings back, not fixes applied.
+
+tools: Bash, Read, Grep, Glob
+
+source_keys:
+  - context7-websites-vale-sh
+
+---
+
+You are a linter runner. When invoked, you run the appropriate linter(s) over the requested scope, collect their findings, and report them back in a structured, reviewable form. You never edit files.
+
+## Inputs
+
+- **scope:** file path, directory path, or glob to lint
+- **linter:** which linter to run (defaults to `vale` — the only backend currently wired up)
+- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini` for Vale, or whatever config format the requested linter expects); if none exists, say so in your report rather than inventing one
+
+## Process
+
+1. Determine whether the target scope already has configuration in place for the requested `linter` (whatever config format that linter expects). If not, use the `<linter>-config` skill (e.g. `vale-config` when `linter` is `vale`) to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
+2. Use the `<linter>-run` skill (e.g. `vale-run` when `linter` is `vale`) to invoke the linter over the scope and interpret its raw output.
+3. Normalize findings into one shape regardless of backend linter: file, line, rule/check, severity, message.
+4. Do not edit, fix, or rewrite any flagged content. If a finding looks trivially fixable, note that in the report — do not act on it.
+5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), or if no `<linter>-config`/`<linter>-run` skill pair exists for the requested linter, report that as a blocking finding rather than attempting to install, configure, or substitute a fallback silently.
+
+## Output
+
+Report findings as a flat list, most-severe first:
+
+```
+- file: <path>
+  line: <line number or range>
+  rule: <check/rule name>
+  severity: <error | warning | suggestion>
+  message: <finding text>
+```
+
+Follow with a one-line summary: total findings by severity, and whether the run was blocked (e.g. linter not configured). If there are zero findings, say so explicitly — do not omit the report.

plugins/lint/docs/README.md

@@ -0,0 +1,27 @@
+# docs/
+
+Plugin documentation. Not read automatically by Claude Code or GitHub Copilot CLI — reference specific files from skill bodies or agent prompts as needed.
+
+## research/
+
+Upstream reference material gathered during skill authoring. Not shipped with the plugin — used at development time only.
+
+| Path | Purpose |
+|------|---------|
+| `research/docs/vale/` | Vale documentation (vale.sh), gathered while authoring `vale-config`/`vale-run` — see below |
+
+### research/docs/vale/
+
+| File | Covers |
+|------|--------|
+| `overview.md` | What Vale is; the style/rule/check configuration model; the built-in `Vale` style's four rules; styles directory layout |
+| `installation.md` | Installing Vale via OS package managers (Homebrew, Snap, Chocolatey) and Docker |
+| `configuration.md` | `.vale.ini` structure — global, `[formats]`, and per-glob sections |
+| `cli-reference.md` | Core invocation and key subcommands/flags (`vale sync`, `vale ls-config`, etc.) |
+| `examples.md` | Walkthroughs — project initialization, typical `.vale.ini` configs |
+| `troubleshooting.md` | Suppressing false positives via inline markup (format-specific `vale off`/`vale on` syntax, spelling ignore lists) |
+| `sources.md` | Provenance record for this directory — source URL, description, and which files above were extracted from it |
+
+Each file's frontmatter carries a `source_keys` entry keyed to the same provenance record. The plugin-level provenance file, `plugins/lint/sources.md`, cross-references this directory from the `context7-websites-vale-sh` entry and lists the agents/skills whose content drew on it.
+
+`vale-config` and `vale-run` are the skills that consume this research — read the relevant file here before changing either skill's Vale-facing behavior.

plugins/lint/docs/research/docs/vale/cli-reference.md

@@ -0,0 +1,29 @@
+---
+topic: cli-reference
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Core Invocation
+
+```bash
+$ vale README.md
+```
+
+Lints the given file(s)/glob against the styles configured in `.vale.ini`.
+
+## Key Flags and Subcommands
+
+| Command/Flag | Purpose |
+|---|---|
+| `vale sync` | Downloads and installs packages/styles declared in `.vale.ini`. Run after install and whenever `Packages` changes. |
+| `vale ls-config` | Prints the currently active, fully-resolved configuration as JSON. Useful for debugging what settings actually apply to a file. |
+| `--output=<style>` | Sets the output format/template: `line`, `JSON`, `CLI` (default), or a custom template. |
+| `--no-exit` | Suppresses the non-zero exit code Vale normally returns when alerts are found — useful in CI pipelines that shouldn't hard-fail on lint output. |
+| `--ignore-syntax` | Treats input as plain, unformatted text, skipping syntax-aware parsing (Markdown/HTML/etc). |
+| `--minAlertLevel=<level>` | Overrides `MinAlertLevel` from the config for this run (`suggestion`, `warning`, `error`). |
+| `--version` | Prints the Vale binary version. |
+
+## Exit Codes
+
+By default, `vale` exits non-zero when it finds any alert at or above `MinAlertLevel` — this is what makes it usable as a CI gate. Pass `--no-exit` to always exit `0` regardless of findings.

plugins/lint/docs/research/docs/vale/configuration.md

@@ -0,0 +1,106 @@
+---
+topic: configuration
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## `.vale.ini` Structure
+
+Configuration is INI-formatted with three sections, in order:
+
+```ini
+# Core settings appear at the top
+# (the "global" section).
+
+[formats]
+# Format associations appear under
+# the optional "formats" section.
+
+[*]
+# Format-specific settings appear
+# under a user-provided "glob"
+# pattern.
+```
+
+Core (global) settings apply application-wide; glob sections (`[*]`, `[*.md]`, etc.) scope settings to files matching that pattern.
+
+## Core Settings
+
+| Key | Type | Purpose |
+|---|---|---|
+| `StylesPath` | string | Path to all Vale-related resources (styles, dictionaries, vocab). |
+| `Packages` | string[] | Packages to download and install via `vale sync`. |
+| `Vocab` | string[] | Vocabularies to load. |
+| `MinAlertLevel` | enum | Minimum severity to report: `suggestion`, `warning`, or `error`. |
+| `IgnoredScopes` | enum | Inline-level HTML tags to ignore. |
+| `SkippedScopes` | enum | Block-level HTML tags to ignore entirely. |
+
+Example:
+
+```ini
+StylesPath = styles
+MinAlertLevel = suggestion
+
+[*.md]
+BasedOnStyles = Vale
+```
+
+## Format Associations
+
+Map an unrecognized extension onto a supported one so Vale lints it with the right parser. This is an extension-level substitution only — it does not add new file-type support:
+
+```ini
+[formats]
+mdx = md
+```
+
+## Vocabularies
+
+Reference a named vocabulary (a folder of accept/reject word lists under `StylesPath`) via `Vocab`, then apply styles per glob:
+
+```ini
+StylesPath = styles
+
+Vocab = Blog
+
+[*]
+BasedOnStyles = Vale, MyStyle
+```
+
+## Packages
+
+Third-party style packages are declared via `Packages` and then activated per glob with `BasedOnStyles`:
+
+```ini
+Packages = Google, write-good
+
+[*.md]
+BasedOnStyles = Vale, Google, write-good
+```
+
+## Local Overrides
+
+A project can layer a local `.vale.ini` that overrides `StylesPath`, adds packages, and changes `BasedOnStyles` for a subset of files — local settings merge with or override the global ones:
+
+```ini
+StylesPath = localpath
+
+Packages = write-good
+
+[*.md]
+BasedOnStyles = write-good
+```
+
+## Rule Header Fields
+
+Individual rule YAML files (under a style's directory) support these header fields:
+
+| Field | Required | Default | Purpose |
+|---|---|---|---|
+| `extends` | yes | — | Check this rule extends (e.g. `existence`). |
+| `message` | yes | — | Message shown when triggered; supports `%s` formatting per check type. |
+| `level` | no | `suggestion` | Severity: `suggestion`, `warning`, or `error`. |
+| `scope` | no | `text` | Scope the rule applies to (e.g. `heading`). |
+| `link` | no | — | URL with more info about the rule. |
+| `limit` | no | — | Max number of triggers per file. |
+| `vocab` | no | `true` | Set `false` to disable active vocabularies for this rule. |

plugins/lint/docs/research/docs/vale/examples.md

@@ -0,0 +1,52 @@
+---
+topic: examples
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Project Initialization Walkthrough
+
+```bash
+$ cd some-project
+# create .vale.ini with StylesPath + BasedOnStyles
+$ vale sync         # downloads declared packages/styles into StylesPath
+$ ls styles          # confirms styles were installed
+$ vale README.md     # lint a file
+```
+
+The `.vale.ini` file must exist before `vale sync` — it declares which packages to fetch.
+
+## Typical Project Config
+
+```ini
+StylesPath = styles
+MinAlertLevel = error
+
+[*.md]
+BasedOnStyles = ProjectStyle
+```
+
+## pre-commit Integration
+
+Vale ships a pre-commit hook definition. A typical setup runs `vale sync` once (with `pass_filenames: false`) plus the actual lint pass with CI-appropriate flags:
+
+```yaml
+repos:
+  - repo: https://github.com/errata-ai/vale
+    rev: 16d3a7f
+    hooks:
+      - id: vale
+        name: vale sync
+        pass_filenames: false
+        args: [sync]
+      - id: vale
+        args: [--output=line, --minAlertLevel=error]
+```
+
+## CI Output for Machine Parsing
+
+```bash
+$ vale --output=JSON README.md
+```
+
+Use `--output=JSON` when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.

plugins/lint/docs/research/docs/vale/installation.md

@@ -0,0 +1,41 @@
+---
+topic: installation
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Package Managers
+
+Vale is distributed via standard OS package managers:
+
+```bash
+brew install vale      # macOS
+snap install vale      # Linux
+```
+
+```powershell
+choco install vale      # Windows
+```
+
+## Docker
+
+An official image is available on Docker Hub:
+
+```bash
+docker pull jdkato/vale
+```
+
+## Post-Install: Syncing Styles
+
+Installing the `vale` binary alone does not install any styles. After install, run `vale sync` to download and install the styles/packages declared in `.vale.ini`:
+
+```bash
+$ vale sync
+```
+
+## Format-Specific Extras
+
+Some input formats need an external converter installed separately before Vale can process them:
+
+- reStructuredText: `pip install docutils` (provides `rst2html`)
+- MDX: `npm install -g mdx2vast`

plugins/lint/docs/research/docs/vale/overview.md

@@ -0,0 +1,43 @@
+---
+topic: overview
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## What Vale Is
+
+Vale is a cross-platform command-line tool that brings code-like linting to prose. Rather than checking general grammar, it enforces project-specific writing style rules — consistency of terminology, phrasing, and formatting — the same way a linter enforces a code style guide.
+
+## Styles, Rules, and Checks
+
+Vale's configuration model has three layers:
+
+- **Styles** — a named collection of rules (e.g. the built-in `Vale` style, or third-party styles like `Google` or `write-good`). A project can apply multiple styles at once via `BasedOnStyles`.
+- **Rules** — individual YAML files that define one specific check (e.g. flag a term, enforce a heading capitalization pattern). Each rule `extends` a check and sets a `message`, `level`, and other header fields.
+- **Checks** — the underlying functions a rule extends to perform analysis: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`.
+
+## Built-in Style
+
+Vale ships with a default `Vale` style containing four rules:
+
+- `Vale.Spelling` — spell-checks against Hunspell-compatible dictionaries in `<StylesPath>/config/dictionaries`.
+- `Vale.Terms` — enforces the project's accepted vocabulary terms.
+- `Vale.Avoid` — enforces the project's rejected vocabulary terms.
+- `Vale.Repetition` — flags repeated words (e.g. "the the").
+
+## Styles Directory Layout
+
+Styles live under `StylesPath` in a nested folder structure, one subdirectory per style, each holding YAML rule files:
+
+```
+styles/
+├── base/
+│   ├── ComplexWords.yml
+│   ├── SentenceLength.yml
+├── blog/
+│   ├── TechTerms.yml
+└── docs/
+    ├── Branding.yml
+```
+
+This lets a project mix a shared base style with format- or section-specific styles, all activated per-glob in `.vale.ini`.

plugins/lint/docs/research/docs/vale/sources.md

@@ -0,0 +1,8 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, CLI commands and flags, installation across package managers and Docker, format-specific inline disable syntax, pre-commit integration, spelling ignore lists.
+- **Contributing files:** overview.md, installation.md, configuration.md, cli-reference.md, examples.md, troubleshooting.md
+- **Status:** `extracted`

plugins/lint/docs/research/docs/vale/troubleshooting.md

@@ -0,0 +1,56 @@
+---
+topic: troubleshooting
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Suppressing False Positives Inline
+
+Vale supports inline markup comments to disable checks for a section of content. Syntax varies by format:
+
+Markdown/MDX:
+```mdx
+{/* vale off */}
+This text will be ignored.
+{/* vale on */}
+```
+
+Org mode:
+```org
+# vale off
+This text will be ignored.
+# vale on
+```
+
+## Disabling a Specific Rule for Specific Matches
+
+Rather than disabling all checks, target one rule and specific known-exception strings, then re-enable:
+
+```mdx
+{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
+This is some text ACT test
+{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}
+```
+
+This is the preferred fix for recurring false positives on specific terms — it keeps the rule active everywhere else instead of disabling it project-wide.
+
+## Ignoring Words in Spell Check
+
+The `spelling` check accepts an `ignore` list of external plain-text files, so known project-specific terms don't need touching the dictionary:
+
+```yaml
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+ignore:
+  - ignore1.txt
+  - ignore2.txt
+```
+
+## Plain-Text Fallback
+
+If a file's syntax-aware parsing produces noisy/incorrect results (e.g. an unsupported or malformed format), rerun with `--ignore-syntax` to treat it as plain text instead of relying on the format-specific parser.
+
+## CI Failing Unexpectedly
+
+If a CI job fails solely because Vale returns a non-zero exit code on found alerts (not because the content is actually wrong for that pipeline stage), add `--no-exit` rather than suppressing the rule itself — this preserves the lint output while not gating the build on it.

plugins/lint/hooks.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

plugins/lint/plugin.json

@@ -0,0 +1,22 @@
+{
+  "agents": "agents/",
+  "author": {
+    "email": "defame1297@rkdr.net",
+    "name": "Defame1297"
+  },
+  "description": "Skills and agents for configuring and running linters.",
+  "hooks": "hooks.json",
+  "keywords": [
+    "lint",
+    "style",
+    "prose",
+    "linter"
+  ],
+  "license": "MIT",
+  "mcpServers": ".mcp.json",
+  "name": "lint",
+  "skills": [
+    "skills/"
+  ],
+  "version": "1.1.2"
+}

plugins/lint/skills/vale-config/README.md

@@ -0,0 +1,23 @@
+# vale-config
+
+Install and configure Vale, the prose/style linter — `.vale.ini`, `StylesPath`, built-in/third-party/custom styles, and activation via `BasedOnStyles`.
+
+## What it does
+
+Covers the setup side of Vale: getting a project from no config to a working `.vale.ini` where `vale sync` runs clean and every declared style is actually activated for the right files. Does not run Vale or interpret its output — see `vale-run` for that.
+
+## Usage
+
+```
+/vale-config
+```
+
+Describe what you want configured: initial setup, adding a third-party style package, or a custom rule. The skill covers install, `StylesPath` layout, `.vale.ini` structure, and `BasedOnStyles` activation.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/configuration-reference.md` | Full `.vale.ini` field and rule-header reference |
+| `references/sources.md` | Research sources backing the Vale configuration guidance |

plugins/lint/skills/vale-config/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: vale-config
+
+description: >
+  Use when installing or configuring Vale, the cross-platform prose/style linter — setting up
+  .vale.ini, choosing a StylesPath, adding built-in, third-party, or custom styles, and activating
+  them per file glob via BasedOnStyles. Covers the setup side of Vale only: getting a project from
+  "no Vale config" to "vale sync runs clean and BasedOnStyles is wired up correctly". Use even if the
+  user doesn't say "Vale" explicitly — "set up prose linting", "lint our docs for style", "enforce a
+  vocabulary/terminology list in markdown" all apply. Do not use when the user wants to actually run
+  Vale and interpret its output on existing config — use vale-run for that.
+
+metadata:
+  category: lint
+  version: "0.1.0"
+  source_keys:
+    - context7-websites-vale-sh
+---
+
+## Gotchas
+
+- Installing the `vale` binary installs no styles. A fresh `.vale.ini` with `BasedOnStyles` set will fail or find nothing until `vale sync` runs and downloads the `Packages` it declares.
+- `.vale.ini` is order-sensitive: global (core) settings first, then the optional `[formats]` section, then glob sections (`[*]`, `[*.md]`, …). Settings in a glob section only apply to files matching that glob.
+- `Packages` (top-level, fetched by `vale sync`) and `BasedOnStyles` (per-glob, activates) are separate keys — a style only lints files once it's in both. This is the step people forget.
+- A rule scoped to `text.frontmatter.<key>` (e.g. `text.frontmatter.description`) only reliably matches when that field's value is a single physical line. If it's a YAML block scalar (`>`/`|`) spanning 2+ physical lines, the scope silently stops matching — no error, just 0 findings — confirmed against Vale 3.15.2. Verify with a deliberately-bad multi-line fixture before trusting a frontmatter-scoped rule in production; if the field is commonly authored as a multi-line block scalar, flatten it to one line ahead of the `vale` call rather than relying on the scope alone.
+
+## Setup workflow
+
+- [ ] **Install** the `vale` binary: `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or `docker pull jdkato/vale`.
+- [ ] **Pick a `StylesPath`** (conventionally `styles`) and create it. This is where all styles, dictionaries, and vocab live.
+- [ ] **Write `.vale.ini`** at the project root with at minimum:
+  ```ini
+  StylesPath = styles
+  MinAlertLevel = suggestion
+
+  [*.md]
+  BasedOnStyles = Vale
+  ```
+  `Vale` here is the built-in style (`Vale.Spelling`, `Vale.Terms`, `Vale.Avoid`, `Vale.Repetition`) — no download needed, it always works.
+- [ ] **Add third-party styles** (optional) by declaring them in `Packages`, then activating them in the same or another glob's `BasedOnStyles`:
+  ```ini
+  Packages = Google, write-good
+
+  [*.md]
+  BasedOnStyles = Vale, Google, write-good
+  ```
+- [ ] **Sync**: run `vale sync` to download everything listed in `Packages` into `StylesPath`.
+- [ ] **Verify activation**: confirm every style named in `Packages` also appears in at least one glob's `BasedOnStyles` — an unreferenced package downloads but never lints anything.
+
+For the full `.vale.ini` field reference (formats mapping, vocab, local overrides, custom rule header fields), read `references/configuration-reference.md`.
+
+## Custom styles
+
+A custom style is just a new subdirectory under `StylesPath`, holding one YAML file per rule:
+
+```
+styles/
+└── MyStyle/
+    └── NoJargon.yml
+```
+
+Each rule file needs `extends` (the check it implements, e.g. `existence`) and `message` at minimum. Activate the style the same way as any other: add `MyStyle` to `BasedOnStyles` for the relevant glob. See `references/configuration-reference.md` for the full rule header field table.

plugins/lint/skills/vale-config/references/configuration-reference.md

@@ -0,0 +1,78 @@
+---
+topic: configuration-reference
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Core Settings
+
+| Key | Type | Purpose |
+|---|---|---|
+| `StylesPath` | string | Path to all Vale-related resources (styles, dictionaries, vocab). |
+| `Packages` | string[] | Packages to download and install via `vale sync`. |
+| `Vocab` | string[] | Vocabularies to load. |
+| `MinAlertLevel` | enum | Minimum severity to report: `suggestion`, `warning`, or `error`. |
+| `IgnoredScopes` | enum | Inline-level HTML tags to ignore. |
+| `SkippedScopes` | enum | Block-level HTML tags to ignore entirely. |
+
+## Format Associations
+
+Map an unrecognized extension onto a supported one so Vale lints it with the right parser — an extension-level substitution only, it does not add new file-type support:
+
+```ini
+[formats]
+mdx = md
+```
+
+## Vocabularies
+
+Reference a named vocabulary (a folder of accept/reject word lists under `StylesPath`) via `Vocab`, then apply styles per glob:
+
+```ini
+StylesPath = styles
+
+Vocab = Blog
+
+[*]
+BasedOnStyles = Vale, MyStyle
+```
+
+## Local Overrides
+
+A project can layer a local `.vale.ini` that overrides `StylesPath`, adds packages, and changes `BasedOnStyles` for a subset of files — local settings merge with or override the global ones:
+
+```ini
+StylesPath = localpath
+
+Packages = write-good
+
+[*.md]
+BasedOnStyles = write-good
+```
+
+## Rule Header Fields
+
+Individual rule YAML files (under a style's directory) support these header fields:
+
+| Field | Required | Default | Purpose |
+|---|---|---|---|
+| `extends` | yes | — | Check this rule extends (e.g. `existence`). |
+| `message` | yes | — | Message shown when triggered; supports `%s` formatting per check type. |
+| `level` | no | `suggestion` | Severity: `suggestion`, `warning`, or `error`. |
+| `scope` | no | `text` | Scope the rule applies to (e.g. `heading`). |
+| `link` | no | — | URL with more info about the rule. |
+| `limit` | no | — | Max number of triggers per file. |
+| `vocab` | no | `true` | Set `false` to disable active vocabularies for this rule. |
+
+## Checks
+
+The underlying functions a rule's `extends` field can reference: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`.
+
+## Built-in Style
+
+Vale ships with a default `Vale` style containing four rules, usable without `vale sync`:
+
+- `Vale.Spelling` — spell-checks against Hunspell-compatible dictionaries in `<StylesPath>/config/dictionaries`.
+- `Vale.Terms` — enforces the project's accepted vocabulary terms.
+- `Vale.Avoid` — enforces the project's rejected vocabulary terms.
+- `Vale.Repetition` — flags repeated words (e.g. "the the").

plugins/lint/skills/vale-config/references/sources.md

@@ -0,0 +1,9 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, installation across package managers and Docker.
+- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
+- **Contributing files:** SKILL.md, references/configuration-reference.md
+- **Status:** `extracted`

plugins/lint/skills/vale-run/README.md

@@ -0,0 +1,23 @@
+# vale-run
+
+Run Vale (a prose/style linter) against an already-configured project and interpret its results.
+
+## What it does
+
+This skill covers invoking the `vale` CLI against files or directories, choosing an output format (human-readable CLI, `line`, or machine-parseable `JSON`), filtering by severity via `--minAlertLevel`, and handling exit codes in scripts and CI. It also covers resolving common runtime issues: false positives, format-specific inline suppression, and CI failures caused solely by Vale's non-zero exit code. It assumes the project already has a working `.vale.ini` and installed styles — setting those up is the sibling `vale-config` skill's job.
+
+## Usage
+
+```
+/vale-run
+```
+
+Describe what you want to lint and how (human-readable output, CI/JSON output, filtered by severity). The skill will pick the right flags and, if results include false positives, walk through the narrowest applicable fix.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Core invocation, key flags, output format guidance, false-positive triage order |
+| `references/troubleshooting.md` | Inline suppression syntax, rule-specific disabling, spelling ignore lists, pre-commit integration, CI edge cases |
+| `references/sources.md` | Research provenance |

plugins/lint/skills/vale-run/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: vale-run
+description: >
+  Use when running Vale (a prose/style linter) against files or directories in an
+  already-configured project — one that already has a .vale.ini — and interpreting
+  or reporting its results: choosing an output format for humans vs. CI, filtering
+  by severity, handling Vale's exit codes in scripts, or resolving common runtime
+  issues like false positives and unexpected CI failures. Use even if the user
+  doesn't say "vale" explicitly, e.g. "lint the docs", "check prose style", "run
+  the style linter", "why is CI failing on the docs check". Do not use when the
+  project has no .vale.ini yet, or needs styles installed/configured — that's the
+  vale-config skill.
+metadata:
+  version: "0.1.1"
+  category: lint
+  source_keys:
+    - context7-websites-vale-sh
+---
+
+## Gotchas
+
+- Vale exits non-zero whenever it finds an alert at or above `MinAlertLevel` — that's what makes it usable as a CI gate, not a sign the invocation failed. Read the output before concluding the command errored.
+- `vale ls-config` prints the fully-resolved, currently active configuration as JSON — the fastest way to check why a rule "isn't applying" is what's actually active, not what's written in `.vale.ini`.
+- Inline suppression syntax is format-specific: Markdown/MDX uses `{/* vale off */}` / `{/* vale on */}`, Org mode uses `# vale off` / `# vale on`. Don't assume one syntax works across formats.
+- Before calling the `vale` binary directly, check whether the target repo documents its own wrapper script for Vale (look in its README, CONTRIBUTING docs, pre-commit config, or a `scripts/` directory). Some projects wrap `vale` to work around real bugs — e.g. a scope that silently stops matching multi-line YAML block-scalar frontmatter fields — and calling bare `vale` in a repo that has such a wrapper silently skips whatever the wrapper works around. If a wrapper is documented, invoke it with the same arguments instead of calling `vale` directly; otherwise fall back to the default below.
+
+## Running vale
+
+Default invocation (when the target repo has no documented Vale wrapper — see Gotchas):
+
+```bash
+vale <path-or-glob>
+```
+
+Key flags:
+
+| Flag | Purpose |
+|---|---|
+| `--output=<style>` | Output format/template: `CLI` (default, human-readable), `line` (compact, one alert per line, good for grep/piping), `JSON` (for programmatic parsing), or a custom template. |
+| `--minAlertLevel=<suggestion\|warning\|error>` | Overrides `MinAlertLevel` from `.vale.ini` for this run only, without editing config. |
+| `--no-exit` | Forces exit code `0` regardless of findings. Use in CI stages that should surface lint output without hard-failing the build. |
+| `--ignore-syntax` | Treats input as plain text, skipping format-aware parsing — use when a file's syntax-aware parser produces noisy or wrong results. |
+
+`vale sync` downloads the packages/styles declared in `.vale.ini` — that's a one-time-per-change setup step (vale-config's territory), not part of a normal lint run. If a run behaves as though no styles are active, that's a sign `vale sync` hasn't been run yet, not a `vale-run` problem.
+
+Prefer `--output=JSON` whenever the caller (a script, a CI step, another agent) needs to act on individual alerts rather than just get a pass/fail signal — `CLI` and `line` are for humans reading the terminal.
+
+## Fixing false positives
+
+Scope the fix as narrowly as possible, in this order:
+
+1. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup.
+2. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (e.g. `{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}` ... `= YES`), rather than the whole rule.
+3. **Known project term failing spell check**: add it to the style's `ignore` list, not an inline suppression.
+
+Never disable a rule project-wide to fix one false positive — editing `.vale.ini`/`BasedOnStyles` is vale-config's job, and it silences the rule everywhere, not just the false-positive case.
+
+If output looks wrong because Vale mis-parsed a file's format, rerun with `--ignore-syntax` before assuming the rule itself is broken.
+
+For CI that fails solely because Vale returned non-zero on found alerts — not because the content is wrong for that pipeline stage — add `--no-exit` rather than disabling the rule.
+
+If setting up Vale as a pre-commit hook or need the full inline-suppression/spelling-ignore syntax reference, read `references/troubleshooting.md`.

plugins/lint/skills/vale-run/references/sources.md

@@ -0,0 +1,9 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, CLI commands and flags, installation across package managers and Docker, format-specific inline disable syntax, pre-commit integration, spelling ignore lists.
+- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
+- **Contributing files:** SKILL.md, references/troubleshooting.md
+- **Status:** `extracted`

plugins/lint/skills/vale-run/references/troubleshooting.md

@@ -0,0 +1,88 @@
+---
+source_keys:
+  - context7-websites-vale-sh
+---
+
+# Vale troubleshooting reference
+
+## Inline suppression syntax by format
+
+Markdown/MDX:
+```mdx
+{/* vale off */}
+This text will be ignored.
+{/* vale on */}
+```
+
+Org mode:
+```org
+# vale off
+This text will be ignored.
+# vale on
+```
+
+## Disabling a specific rule for specific matches
+
+Targets one rule and specific known-exception strings, then re-enables — the preferred fix for a recurring false positive on a specific term, since it keeps the rule active everywhere else:
+
+```mdx
+{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
+This is some text ACT test
+{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}
+```
+
+## Ignoring words in spell check
+
+The `spelling` check accepts an `ignore` list of external plain-text files, so project-specific terms don't need touching the dictionary:
+
+```yaml
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+ignore:
+  - ignore1.txt
+  - ignore2.txt
+```
+
+## Plain-text fallback
+
+If a file's syntax-aware parsing produces noisy or incorrect results (an unsupported or malformed format), rerun with `--ignore-syntax` to treat it as plain text instead of relying on the format-specific parser.
+
+## CI failing unexpectedly
+
+If a CI job fails solely because Vale returns a non-zero exit code on found alerts — not because the content is actually wrong for that pipeline stage — add `--no-exit` rather than suppressing the rule itself. This preserves the lint output while not gating the build on it.
+
+## pre-commit integration
+
+Vale ships a pre-commit hook definition. A typical setup runs `vale sync` once (with `pass_filenames: false`) plus the actual lint pass with CI-appropriate flags:
+
+```yaml
+repos:
+  - repo: https://github.com/errata-ai/vale
+    rev: 16d3a7f
+    hooks:
+      - id: vale
+        name: vale sync
+        pass_filenames: false
+        args: [sync]
+      - id: vale
+        args: [--output=line, --minAlertLevel=error]
+```
+
+If the project has documented a wrapper script for a known Vale scope/escaping limitation (see the Gotchas section of `SKILL.md`), point the second hook's `entry:` at that wrapper instead of at bare `vale`, even though the hook's `repo`/`rev`/`id` still come from the upstream definition above — only the invocation target changes:
+
+```yaml
+      - id: vale
+        entry: <path-to-project-wrapper>
+        args: [--output=line, --minAlertLevel=error]
+```
+
+Using the upstream hook's bare `vale` entry in a project that has such a wrapper reintroduces exactly the bug the wrapper exists to fix.
+
+## CI output for machine parsing
+
+```bash
+$ vale --output=JSON README.md
+```
+
+Use `--output=JSON` when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.

plugins/lint/sources.md

@@ -0,0 +1,9 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — informed `lint-runner`'s report-only design: normalizing findings to a `file, line, rule/check, severity, message` shape and deferring linter-specific invocation to `<linter>-config`/`<linter>-run` skills, drawing on Vale's CLI output format and exit-code conventions.
+- **Contributing files:** agents/lint-runner.md, agents/lint-runner.agent.md
+- **Status:** `extracted`

scripts/skill-size-check.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Enforces agentskills.io's skill-authoring.md guidance: keep SKILL.md under 500
+# lines and roughly 5,000 tokens, so the full body doesn't crowd out conversation
+# history and other active skills once loaded into context. Vale can't express
+# a whole-file length ceiling (its checks operate on text patterns, not raw
+# file size), so this is a plain script instead of a Vale rule.
+#
+# Token counts aren't computed exactly here — word count (`wc -w`) is used as
+# a proxy. This repo's own SKILL.md corpus measures ~5.7-6.5 characters per
+# word, which at the standard ~4-characters-per-token English approximation
+# works out to roughly 1.6-1.7 tokens per word. MAX_WORDS below is calibrated
+# from that measured ratio against the 5,000-token ceiling, with margin — it's
+# still a proxy, not exact BPE tokenization, but now grounded in actual repo
+# content rather than an unverified "conservative" assumption.
+
+MAX_LINES=500
+MAX_WORDS=2900
+FAIL=0
+
+for f in "$@"; do
+  [[ -f "$f" ]] || continue
+
+  # awk's NR counts the final line even without a trailing newline, matching
+  # Python's splitlines() semantics (used by skill-audit/scripts/validate.sh
+  # for its own line count) — `wc -l` undercounts by 1 in that case.
+  lines=$(awk 'END{print NR}' "$f")
+  if (( lines >= MAX_LINES )); then
+    echo "ERROR: $f has $lines lines, at or over the $MAX_LINES-line ceiling (agentskills.io skill-authoring.md)" >&2
+    FAIL=1
+  fi
+
+  words=$(wc -w < "$f")
+  if (( words > MAX_WORDS )); then
+    echo "ERROR: $f has $words words (proxy for tokens), exceeding the $MAX_WORDS-word ceiling (~5,000 tokens, agentskills.io skill-authoring.md)" >&2
+    FAIL=1
+  fi
+done
+
+exit $FAIL

scripts/vale-wrap.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Works around a Vale limitation: the `text.frontmatter.description` NLP scope
+# silently stops matching once the `description:` value is a YAML block scalar
+# (`>`/`|`) spanning 2+ physical lines — the style used by most skills/agents in
+# this repo. Flattens the description to one physical line in a scratch copy
+# (padding with blank lines so every other line number is unchanged), then runs
+# the real `vale` binary against the copies. Drop-in replacement for calling
+# `vale` directly: same args, same exit code.
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+vale_args=()
+files=()
+config_next=false
+for arg in "$@"; do
+  if [[ "$config_next" == true ]]; then
+    if [[ "$arg" == /* ]]; then
+      vale_args+=("$arg")
+    else
+      vale_args+=("$repo_root/$arg")
+    fi
+    config_next=false
+    continue
+  fi
+  if [[ "$arg" == "--config" ]]; then
+    vale_args+=("$arg")
+    config_next=true
+    continue
+  fi
+  if [[ "$arg" == --config=* ]]; then
+    cfg="${arg#--config=}"
+    if [[ "$cfg" == /* ]]; then
+      vale_args+=("--config=$cfg")
+    else
+      vale_args+=("--config=$repo_root/$cfg")
+    fi
+    continue
+  fi
+  if [[ "$arg" != -* && -f "$repo_root/$arg" ]]; then
+    files+=("$arg")
+  elif [[ "$arg" == /* && -f "$arg" && "$arg" == "$repo_root"/* ]]; then
+    files+=("${arg#"$repo_root"/}")
+  else
+    vale_args+=("$arg")
+  fi
+done
+
+if [[ ${#files[@]} -eq 0 ]]; then
+  exec vale "${vale_args[@]}" < /dev/null
+fi
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+for rel in "${files[@]}"; do
+  dest="$tmpdir/$rel"
+  mkdir -p "$(dirname "$dest")"
+  python3 - "$repo_root/$rel" "$dest" <<'PYTHON'
+import re
+import sys
+
+src, dest = sys.argv[1], sys.argv[2]
+with open(src) as fh:
+    content = fh.read()
+
+fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
+if fm_match:
+    fm = fm_match.group(2)
+    # Only `>`/`>-`/`>+` (folded) scalars break Vale's frontmatter-description
+    # scope. `|`/`|-`/`|+` (literal) scalars already work fine with bare vale,
+    # so they're deliberately left unmatched here.
+    header_m = re.search(r'^description:[ \t]*(>[+-]?)[ \t]*\n', fm, re.MULTILINE)
+    if header_m:
+        # Body capture is indentation-based and blank-line-tolerant, per YAML
+        # block-scalar rules: a blank line (any amount of whitespace) always
+        # stays inside the block; the indent is set by the first content line;
+        # the block ends at the first line indented less than that, or EOF.
+        rest = fm[header_m.end():]
+        indent = None
+        body_lines = []
+        for line in rest.splitlines(keepends=True):
+            text = line.rstrip('\n')
+            if text.strip() == '':
+                body_lines.append(line)
+                continue
+            line_indent = len(text) - len(text.lstrip(' \t'))
+            if indent is None:
+                indent = line_indent
+            elif line_indent < indent:
+                break
+            body_lines.append(line)
+        raw = ''.join(body_lines)
+        if raw.count('\n') >= 2:
+            flat = re.sub(r'\s+', ' ', raw).strip()
+            # YAML single-quoted scalars have no backslash-escape mechanism at
+            # all, so wrapping in single quotes sidesteps the backslash-escape
+            # bug entirely for embedded double quotes, backslashes, and
+            # non-ASCII text. The one YAML-spec-correct way to embed a literal
+            # apostrophe is to double it ('') — but Vale's own frontmatter
+            # scanner isn't a full YAML parser and doesn't understand that
+            # doubling: empirically, it silently truncates the value at the
+            # first ' it sees, hiding everything after it from the NLP scope
+            # (a different flavor of the same bug this whole script exists to
+            # work around). Since this copy is scratch-only and never written
+            # back, sidestep it by substituting a Unicode right single
+            # quotation mark (U+2019) for any literal apostrophe instead of
+            # doubling it — visually a smart quote, but never triggers a YAML
+            # escape sequence at all.
+            flat_q = "'" + flat.replace("'", "’") + "'"
+            pad = '\n' * raw.count('\n')
+            start = header_m.start()
+            end = header_m.end() + len(raw)
+            new_fm = fm[:start] + f'description: {flat_q}\n{pad}' + fm[end:]
+            content = fm_match.group(1) + new_fm + fm_match.group(3) + content[fm_match.end():]
+
+with open(dest, 'w') as fh:
+    fh.write(content)
+PYTHON
+done
+
+cd "$tmpdir"
+vale "${vale_args[@]}" "${files[@]}"

styles/Kyberforge/DescriptionOpener.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Description opens with '%s' — use an imperative 'Use when...' opener instead"
+level: error
+scope: text.frontmatter.description
+ignorecase: true
+raw:
+  - '^This (skill|agent)\b'

styles/Kyberforge/PaddingPhrase.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Generic reference pointer: '%s' — use the specific 'If X, read `references/file.md`' form instead"
+level: warning
+scope: text
+ignorecase: true
+raw:
+  - 'see references?/? for (more )?(info|information|details)\b'

styles/Kyberforge/SentenceOpenerThereIs.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Don't start a sentence with '%s' — name the subject directly"
+level: warning
+scope: sentence
+ignorecase: false
+raw:
+  - '^There\s(is|are)\b'

styles/Kyberforge/VagueQualifier.yml

@@ -0,0 +1,19 @@
+extends: existence
+message: "'%s' is vague filler wording — state the point precisely instead"
+level: warning
+scope: text
+ignorecase: true
+tokens:
+  - easily
+  - everyone knows
+  - exceedingly
+  - excellent
+  - extremely
+  - huge
+  - interestingly
+  - of course
+  - quite
+  - remarkably
+  - surprisingly
+  - vast
+  - very

styles/Kyberforge/VagueWording.yml

@@ -0,0 +1,10 @@
+extends: existence
+message: "Vague capability wording: '%s' — state the capability precisely instead"
+level: warning
+scope: text.frontmatter.description
+ignorecase: true
+tokens:
+  - helps with
+  - utilize
+  - assists with
+  - used for

styles/KyberforgeCopilot/ProactivePhrase.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "'%s' is CC-specific phrasing with no effect in Copilot descriptions — remove it"
+level: warning
+scope: text.frontmatter.description
+ignorecase: true
+tokens:
+  - Use proactively

tests/test-skill-size-check.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# Regression test for scripts/skill-size-check.sh: enforces agentskills.io's
+# 500-line/5,000-word(proxy-for-token) SKILL.md size ceiling.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT="$REPO_ROOT/scripts/skill-size-check.sh"
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+make_fixture() {
+  local name="$1" lines="$2" words_per_line="$3" file
+  file="$TMPDIR/$name.md"
+  {
+    echo "---"
+    echo "name: $name"
+    echo "description: Test fixture."
+    echo "---"
+    for ((i = 1; i <= lines; i++)); do
+      w=""
+      for ((j = 1; j <= words_per_line; j++)); do
+        w="$w word"
+      done
+      echo "$w"
+    done
+  } > "$file"
+  echo "$file"
+}
+
+echo ""
+echo "--- passes a file under both limits ---"
+SMALL="$(make_fixture small 10 5)"
+if "$SCRIPT" "$SMALL"; then
+  pass "file under both limits exits 0"
+else
+  fail "file under both limits should have exited 0"
+fi
+
+echo ""
+echo "--- fails a file over the line limit ---"
+MANY_LINES="$(make_fixture many-lines 600 1)"
+if "$SCRIPT" "$MANY_LINES" 2>/dev/null; then
+  fail "file over the 500-line ceiling should have exited non-zero"
+else
+  pass "file over the 500-line ceiling exits non-zero"
+fi
+
+echo ""
+echo "--- fails a file over the word-count limit ---"
+MANY_WORDS="$(make_fixture many-words 10 600)"
+if "$SCRIPT" "$MANY_WORDS" 2>/dev/null; then
+  fail "file over the 5,000-word ceiling should have exited non-zero"
+else
+  pass "file over the 5,000-word ceiling exits non-zero"
+fi
+
+# Boundary-pair tests below read the script's current MAX_WORDS rather than
+# hardcoding it, so they don't silently drift if the threshold changes again.
+MAX_WORDS="$(grep -oE '^MAX_WORDS=[0-9]+' "$SCRIPT" | cut -d= -f2)"
+MAX_LINES="$(grep -oE '^MAX_LINES=[0-9]+' "$SCRIPT" | cut -d= -f2)"
+
+# make_line_fixture builds a file with an exact total line count (frontmatter
+# included), independent of word count, for the line-boundary tests.
+make_line_fixture() {
+  local name="$1" total_lines="$2" file body_lines
+  file="$TMPDIR/$name.md"
+  {
+    echo "---"
+    echo "name: $name"
+    echo "description: Test fixture."
+    echo "---"
+  } > "$file"
+  body_lines=$((total_lines - 4))
+  for ((i = 1; i <= body_lines; i++)); do
+    echo "word"
+  done >> "$file"
+  echo "$file"
+}
+
+# The line ceiling is exclusive of the limit itself ("stay under $MAX_LINES
+# lines", per skill-authoring.md), enforced via `>=` — so $((MAX_LINES - 1))
+# must pass and $MAX_LINES itself must already fail.
+echo ""
+echo "--- passes a file at $((MAX_LINES - 1)) lines, just under the $MAX_LINES-line boundary ---"
+AT_LINES="$(make_line_fixture at-line-limit "$((MAX_LINES - 1))")"
+ACTUAL_LINES=$(awk 'END{print NR}' "$AT_LINES")
+if [[ "$ACTUAL_LINES" -ne "$((MAX_LINES - 1))" ]]; then
+  fail "fixture has $ACTUAL_LINES lines, expected exactly $((MAX_LINES - 1))"
+elif "$SCRIPT" "$AT_LINES"; then
+  pass "file at $((MAX_LINES - 1)) lines exits 0"
+else
+  fail "file at $((MAX_LINES - 1)) lines should have exited 0"
+fi
+
+echo ""
+echo "--- fails a file at exactly the $MAX_LINES-line boundary ---"
+OVER_LINES="$(make_line_fixture over-line-limit "$MAX_LINES")"
+ACTUAL_OVER_LINES=$(awk 'END{print NR}' "$OVER_LINES")
+if [[ "$ACTUAL_OVER_LINES" -ne "$MAX_LINES" ]]; then
+  fail "fixture has $ACTUAL_OVER_LINES lines, expected exactly $MAX_LINES"
+elif "$SCRIPT" "$OVER_LINES" 2>/dev/null; then
+  fail "file at exactly $MAX_LINES lines should have exited non-zero (>= ceiling, the boundary bug this test guards against)"
+else
+  pass "file at exactly $MAX_LINES lines exits non-zero"
+fi
+
+# make_word_fixture builds a file with an exact total word count (frontmatter
+# words included, since the script's `wc -w` counts the whole file) by padding
+# a body line with just enough "word" tokens to close the gap to the target.
+make_word_fixture() {
+  local name="$1" target="$2" file cur remaining body
+  file="$TMPDIR/$name.md"
+  {
+    echo "---"
+    echo "name: $name"
+    echo "description: Test fixture."
+    echo "---"
+  } > "$file"
+  cur=$(wc -w < "$file")
+  remaining=$((target - cur))
+  body=""
+  for ((i = 1; i <= remaining; i++)); do
+    body="$body word"
+  done
+  echo "$body" >> "$file"
+  echo "$file"
+}
+
+echo ""
+echo "--- passes a file at exactly the $MAX_WORDS-word boundary ---"
+AT_WORDS="$(make_word_fixture at-word-limit "$MAX_WORDS")"
+ACTUAL_WORDS=$(wc -w < "$AT_WORDS")
+if [[ "$ACTUAL_WORDS" -ne "$MAX_WORDS" ]]; then
+  fail "fixture has $ACTUAL_WORDS words, expected exactly $MAX_WORDS"
+elif "$SCRIPT" "$AT_WORDS"; then
+  pass "file at exactly $MAX_WORDS words exits 0"
+else
+  fail "file at exactly $MAX_WORDS words should have exited 0"
+fi
+
+echo ""
+echo "--- fails a file one word over the $MAX_WORDS-word boundary ---"
+OVER_WORDS="$(make_word_fixture over-word-limit "$((MAX_WORDS + 1))")"
+ACTUAL_OVER_WORDS=$(wc -w < "$OVER_WORDS")
+if [[ "$ACTUAL_OVER_WORDS" -ne "$((MAX_WORDS + 1))" ]]; then
+  fail "fixture has $ACTUAL_OVER_WORDS words, expected exactly $((MAX_WORDS + 1))"
+elif "$SCRIPT" "$OVER_WORDS" 2>/dev/null; then
+  fail "file at $((MAX_WORDS + 1)) words should have exited non-zero"
+else
+  pass "file at $((MAX_WORDS + 1)) words exits non-zero"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]]

tests/test-vale-wrap.sh

@@ -0,0 +1,287 @@
+#!/usr/bin/env bash
+# Regression test for scripts/vale-wrap.sh: Vale's `text.frontmatter.description`
+# NLP scope silently stops matching when the description value is a YAML block
+# scalar spanning 2+ physical lines. vale-wrap.sh flattens it to one line before
+# handing off to the real vale binary — this asserts that actually happens.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT="$REPO_ROOT/scripts/vale-wrap.sh"
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+if ! command -v vale &>/dev/null; then
+  echo "vale is not installed — skipping (matches skill-audit/agent-audit's own fallback behavior)"
+  exit 0
+fi
+
+make_fixture() {
+  local dir desc_lines file
+  dir="$(mktemp -d)"
+  (cd "$dir" && git init -q)
+  mkdir -p "$dir/plugins/testplugin/skills/zzzskill"
+  desc_lines="$1"
+  file="$dir/plugins/testplugin/skills/zzzskill/SKILL.md"
+  {
+    echo "---"
+    echo "name: zzzskill"
+    echo "description: >"
+    for ((i = 1; i <= desc_lines; i++)); do
+      echo "  Line $i mentions helps with and utilize, plus a colon: like this."
+    done
+    echo "---"
+    echo ""
+    echo "Body."
+  } > "$file"
+  echo "$dir"
+}
+
+# --- 1. A known-bad single-line description is caught (sanity check on Vale itself) ---
+echo ""
+echo "--- catches vague wording in a single-line description ---"
+FIXTURE1="$(make_fixture 1)"
+trap 'rm -rf "$FIXTURE1"' EXIT
+if (cd "$FIXTURE1" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+  pass "flags vague wording when description is a single physical line"
+else
+  fail "did not flag known-bad single-line description"
+fi
+
+# --- 2. The same known-bad wording across 2+ physical lines is still caught ---
+echo ""
+echo "--- catches vague wording in a multi-line folded description ---"
+FIXTURE2="$(make_fixture 2)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2"' EXIT
+if (cd "$FIXTURE2" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+  pass "flags vague wording when description spans 2+ physical lines"
+else
+  fail "silently missed known-bad wording in a multi-line description — the bug this test guards against"
+fi
+
+# --- 3. Line count is preserved so unrelated report line numbers don't shift ---
+echo ""
+echo "--- preserves total line count when flattening ---"
+FIXTURE3="$(make_fixture 3)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3"' EXIT
+ORIG_LINES=$(wc -l < "$FIXTURE3/plugins/testplugin/skills/zzzskill/SKILL.md")
+OUT=$(cd "$FIXTURE3" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1 || true)
+MAX_LINE=$(echo "$OUT" | grep -oE '^[[:space:]]*[0-9]+:[0-9]+' | tr -d '[:space:]' | cut -d: -f1 | sort -n | tail -1)
+if [[ -n "$MAX_LINE" ]] && (( MAX_LINE <= ORIG_LINES )); then
+  pass "reported line numbers stay within the original file's line count"
+else
+  fail "reported line number ($MAX_LINE) exceeds original file line count ($ORIG_LINES)"
+fi
+
+# make_raw_fixture writes stdin verbatim to a fresh fixture's SKILL.md, for
+# cases where the exact description body needs to be hand-crafted rather than
+# generated from the desc_lines loop above.
+make_raw_fixture() {
+  local dir
+  dir="$(mktemp -d)"
+  (cd "$dir" && git init -q)
+  mkdir -p "$dir/plugins/testplugin/skills/zzzskill"
+  cat > "$dir/plugins/testplugin/skills/zzzskill/SKILL.md"
+  echo "$dir"
+}
+
+# --- 4. A folded description containing a double quote is still caught ---
+# This is the exact case that silently passed (zero alerts) before switching
+# from json.dumps (double-quoted, backslash-escaped) to a single-quoted scalar.
+echo ""
+echo "--- catches vague wording when the folded description contains a double quote ---"
+FIXTURE4="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Use when the user says "audit this skill" and helps with and utilize things.
+  Second line continues the same folded scalar for flattening.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4"' EXIT
+if (cd "$FIXTURE4" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+  pass "flags vague wording when the description contains a double quote"
+else
+  fail "silently missed vague wording in a description containing a double quote — the bug this test guards against"
+fi
+
+# --- 5. A folded description containing an apostrophe fires and stays valid YAML ---
+echo ""
+echo "--- catches vague wording when the folded description contains an apostrophe ---"
+FIXTURE5="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Use when the user's task helps with and utilize things across two lines.
+  Second continuation line for the fold.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5"' EXIT
+OUT5=$(cd "$FIXTURE5" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1)
+if echo "$OUT5" | grep -q "VagueWording"; then
+  pass "flags vague wording when the description contains an apostrophe"
+else
+  fail "silently missed vague wording in a description containing an apostrophe"
+fi
+if echo "$OUT5" | grep -qi "yaml:"; then
+  fail "flattened copy with an apostrophe produced a YAML parse error"
+else
+  pass "flattened copy with an apostrophe is valid YAML (no parse error)"
+fi
+
+# --- 6. A folded description with a backslash and a non-ASCII character ---
+echo ""
+echo "--- catches vague wording when the folded description has a backslash and non-ASCII text ---"
+FIXTURE6="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Use when the café résumé naïve thing helps with and utilize things here.
+  Path is C:\Users\test and this is the second continuation line.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6"' EXIT
+if (cd "$FIXTURE6" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+  pass "flags vague wording when the description has a backslash and non-ASCII text"
+else
+  fail "silently missed vague wording in a description with a backslash and non-ASCII text"
+fi
+
+# --- 7. A folded description with a blank line between two paragraphs ---
+echo ""
+echo "--- handles a blank line inside a folded description without crashing ---"
+FIXTURE7="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Use when the user needs a general helper.
+
+  Do not use when this helps with and utilize things instead.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7"' EXIT
+OUT7=$(cd "$FIXTURE7" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1)
+if echo "$OUT7" | grep -q "Traceback"; then
+  fail "crashed while flattening a description with a blank line between paragraphs"
+elif echo "$OUT7" | grep -q "VagueWording"; then
+  pass "still flags vague wording in the second paragraph after a blank line"
+else
+  fail "silently missed vague wording in the second paragraph after a blank line — the bug this test guards against"
+fi
+
+# --- 8. --config=<path> (equals form) resolves the same as the two-argv form ---
+echo ""
+echo "--- --config=<path> equals form resolves from a subdirectory like the two-argv form ---"
+FIXTURE8="$(mktemp -d)"
+(cd "$FIXTURE8" && git init -q)
+cp "$REPO_ROOT/.vale.ini" "$FIXTURE8/.vale.ini"
+cp -r "$REPO_ROOT/styles" "$FIXTURE8/styles"
+mkdir -p "$FIXTURE8/plugins/testplugin/skills/zzzskill"
+{
+  echo "---"
+  echo "name: zzzskill"
+  echo "description: >"
+  echo "  Line one mentions helps with and utilize, plus a colon: like this."
+  echo "  Line two continues the same folded scalar for flattening."
+  echo "---"
+  echo ""
+  echo "Body."
+} > "$FIXTURE8/plugins/testplugin/skills/zzzskill/SKILL.md"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8"' EXIT
+SUBDIR8="$FIXTURE8/plugins/testplugin/skills/zzzskill"
+REL8="plugins/testplugin/skills/zzzskill/SKILL.md"
+OUT_EQ=$(cd "$SUBDIR8" && bash "$SCRIPT" --config=.vale.ini "$REL8" 2>&1)
+OUT_TWO=$(cd "$SUBDIR8" && bash "$SCRIPT" --config .vale.ini "$REL8" 2>&1)
+if echo "$OUT_EQ" | grep -q "VagueWording" && [[ "$OUT_EQ" == "$OUT_TWO" ]]; then
+  pass "--config=<path> from a subdirectory resolves and matches the two-argv form"
+else
+  fail "--config=<path> equals form did not resolve the same as the two-argv form"
+fi
+
+# --- 9. Zero file args (or a file list that filters to nothing) exits promptly ---
+echo ""
+echo "--- exits promptly instead of hanging on stdin when no files are passed ---"
+if timeout 5 bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" < <(sleep 100) >/dev/null 2>&1; then
+  pass "exits promptly with zero file args"
+else
+  RC=$?
+  if [[ $RC -eq 124 ]]; then
+    fail "hung waiting on stdin with zero file args — the bug this test guards against"
+  else
+    pass "exits promptly (nonzero exit) with zero file args"
+  fi
+fi
+
+echo ""
+echo "--- exits promptly when a file list filters down to nothing ---"
+if timeout 5 bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" --no-such-flag < <(sleep 100) >/dev/null 2>&1; then
+  pass "exits promptly when no file-shaped args remain"
+else
+  RC=$?
+  if [[ $RC -eq 124 ]]; then
+    fail "hung waiting on stdin when the file list filtered to nothing — the bug this test guards against"
+  else
+    pass "exits promptly (nonzero exit) when the file list filters to nothing"
+  fi
+fi
+
+# --- 10. An absolute path to the fixture SKILL.md is still linted, not skipped ---
+echo ""
+echo "--- lints an absolute path to a skill file instead of silently skipping it ---"
+FIXTURE10="$(make_fixture 2)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10"' EXIT
+ABS_FILE10="$FIXTURE10/plugins/testplugin/skills/zzzskill/SKILL.md"
+if (cd "$FIXTURE10" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" "$ABS_FILE10") | grep -q "VagueWording"; then
+  pass "an absolute path under repo_root is linted, not silently skipped"
+else
+  fail "an absolute path under repo_root was silently skipped — the bug this test guards against"
+fi
+
+# --- 11. A literal (|) block scalar passes through unflattened (no regression) ---
+echo ""
+echo "--- leaves a literal (|) block scalar untouched (narrowed >-only scope) ---"
+FIXTURE11="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: |
+  Line one mentions helps with and utilize things here.
+  Line two continues the literal block scalar for this test.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11"' EXIT
+REL11="plugins/testplugin/skills/zzzskill/SKILL.md"
+WRAPPED_OUT=$(cd "$FIXTURE11" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" "$REL11" 2>&1 || true)
+BARE_OUT=$(cd "$FIXTURE11" && vale --config "$REPO_ROOT/.vale.ini" "$REL11" 2>&1 || true)
+if [[ "$WRAPPED_OUT" == "$BARE_OUT" ]]; then
+  pass "literal (|) block scalar output matches bare vale exactly — untouched by flattening"
+else
+  fail "wrapper altered output for a literal (|) block scalar description — should be left untouched"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]]