# Skill Lint > Internal agentic-workflow maintenance: after SKILL.md edits, lint the repo's authoring rules, the machine-surface registration rules and the skill-content smell/security checks. Triggers: "lint the skill", "skill authoring check", "check the skill rules", "scan skills for smells". - Skill: `gtrabanco/skill-lint` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx get-skill add gtrabanco/skill-lint` - Raw SKILL.md: https://api.skillmd.com/api/skills/gtrabanco/skill-lint/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: gtrabanco (https://skillmd.com/u/gtrabanco) - Updated: 2026-11-11 - Page: https://skillmd.com/skills/gtrabanco/skill-lint --- ## Turn contract Load and verify the **canonical** [Turn contract](../orchestration-envelope/references/TURN_CONTRACT.md) before ending every turn; the **read-only profile** substitutes boxes 1–5 (the lint reports only — nothing was edited, committed, pushed, or created; its one sanctioned output is the git add + commit command block printed for the human, never executed). Skill-specific additions: ``` ✓ `bun scripts/skill-lint.mjs` ran and its report block is pasted verbatim (a `PASS` verdict, or every `FINDING` line as printed) ✓ The eight authoring rules were checked against each changed SKILL.md (`references/DISCOVERY_AND_LINT.md`) — including the two machine-surface parity/ordering checks, the internal-skill discovery-exclusion check and the published-vocabulary check — and every violation was reported ✓ Nothing was repaired, added or rewritten — the lint reports only ✓ The git add + commit command block is printed as the ABSOLUTE last output ``` Missing reference → STOP. About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first. ## When to use After any edit to one or more `skills//SKILL.md` files (or to a `references/` file beside one) in this repo, before committing. The skill is **lint-only**: it reports, never repairs, and it bumps nothing — skills carry the unified train version, stamped by `scripts/release.mjs apply` at cut time (D-40-14), and a skill change ships via a `.changeset/` intent file. ## Step 0 — Orientation This skill is **specific to the `agentic-workflow` repository**. Before doing anything, confirm you are in that repo (presence of `skills/` + `CHANGELOG.md`). If not, stop and tell the user. ## Process ### 1. Run the content checks The mechanical half is code: ``` bun scripts/skill-lint.mjs # the whole tree — the sweep bun scripts/skill-lint.mjs --skill # only the skill(s) you changed ``` Paste its block verbatim. The seven checks (hidden comments, frontmatter tags, invisible codepoints, unpinned URLs, credential/exfiltration shapes, backslash paths, time-sensitive claims), the shapes each admits and the smells this repo deliberately does not adopt are owned by [skill content checks](references/CHECKS.md). Exit `0` is `PASS`, `1` is `FAIL`, `2` is a usage error — never re-read the block for a verdict the exit code already gave. ### 2. Lint, warn, never repair Check all eight `AGENTS.md` authoring invariants per [change discovery and authoring lint](references/DISCOVERY_AND_LINT.md). Report every violation without fixing it. These are structure and registration rules (closing block, phase labels, portability, turn contract, plugin registration and its order, internal-skill metadata); the content checks in step 1 do not cover them, and they do not cover the content checks. ### 3. Print a summary and the next step Paste both results (the scanner block, then the authoring-rule findings), then print the next step: > Lint reported. Stage and commit: > ``` > git add skills//SKILL.md .changeset/ > git commit -m "(skills): " > ``` > A skill change must ship with a `.changeset/*.md` intent file declaring the > Pi package — `scripts/lint-changeset.mjs` lints it and the version-parity > gate enforces it. ## Guardrails - **Never change anything in a SKILL.md** — this skill reports; the writer is you, the editor, and the version stamper is `scripts/release.mjs apply`. - **Never commit or push** — this skill only lints and reports. - **Never weaken a check to get a green** — a finding is repaired in the prose that caused it, or recorded as a decision in `references/CHECKS.md`; the patterns live in `scripts/skill-lint.mjs` and are pinned by its suite. - If a skill file is not tracked by git (new file not yet added), say so in the report — the change-discovery step cannot see it. ## Portability (agents other than Claude Code) This skill is repo-maintenance for `agentic-workflow` itself, but the repo may be worked on from any agent: - **No slash-command menu** — follow this `SKILL.md` directly after editing any skill, before committing. - **No per-skill `model:`/`effort:`** — a mid-tier model is enough; this is classification + lint bookkeeping. The content checks are code, so they give the same answer on any model. - **No `bun`-only assumption** — `bun scripts/skill-lint.mjs` is the form to print. The fallback is `node scripts/skill-lint.mjs`: same argv, same block. ## Relationship to other skills - Run after any manual edit to a skill or after `execute-phase` touches a skill file, and before the commit. - `AGENTS.md` section "One version: the unified train" is the policy this skill lints against. - The version-parity gate (`scripts/version-parity-gate.mjs`) is the CI half: a skills change must ship with a `.changeset/` intent file (or a package bump + companion row). - Context budgets are not this skill's: `scripts/check-skill-context.mjs` owns them, and `references/CHECKS.md` records that as a deliberate skip. - Renames and other breaking surfaces feed `docs/workflow/MIGRATION.md`, which `init-workspace` reads when installing. ## Done when - The scanner's block is pasted and every `FINDING` line is reported for the user to fix before committing — or the verdict is `PASS`. - All eight authoring-rule violations (missing `→ Next:` block, `S1`/"Step" phase labels, a `user-invocable: true` skill absent from `plugin.json`, a non-alphabetical machine surface, a drifted `Sev`/`Impact` cell, …) are reported for the user to fix before committing. - **The next step is printed** — the `git add` + `git commit` command, ready to run.