Skip to content

Skills And Scripts

Question

Great, now it understands infrastructure lifecycles, but the code quality is not exactly great, so how do I fix that?

Solution

Now we bring in a linter, autoformatter, and autodocs tooling, and we wrap that all in a skill to ensure it runs properly.

Explanation

"Wrap it in a skill" is doing real work in that sentence. It would be faster to just tell an agent "run shfmt on anything you touch" and move on - and that works, right up until a different agent, or the same one next week, does not know that rule exists. A skill is that rule made discoverable and self-contained:

.agents/skills/shell-fmt/
├── scripts
│   └── shfmt-wrapper
├── SKILL.md
└── tests
    └── shfmt-wrapper
        ├── already-formatted
        ├── needs-reformatting
        ├── run-tests.sh
        └── unparseable

Source: .agents/skills/shell-fmt/

SKILL.md's own description: is what makes this discoverable - an agent reads the whole skill list up front and picks this one up on its own the moment formatting is relevant, the same way a human would scan a table of contents. scripts/shfmt-wrapper is a thin wrapper, not a reimplementation: it still calls the real shfmt binary, just always the same pinned version, found the same way, whether that is a laptop or a CI job.

A skill wrapping a real tool should still explain itself like one - shfmt-wrapper --help prints a real usage message, not just an error string shown only once something has already gone wrong:

usage: shfmt-wrapper [--conf|--exclude PATH] [--githook-precommit] [--write]

  (no flags)            discover every shell file, check its formatting
  --conf <path>         check an exact, fixed list instead of discovering
  --exclude <path>      a different exclude file than ci/shfmt-wrapper.conf
  --githook-precommit   check only staged files, from the discovered set
  --write               apply shfmt -i2 -w in place, instead of checking
  -h, --help            show this message

Source: .agents/skills/shell-fmt/scripts/shfmt-wrapper

  • (no flags) is discovery mode: every shell script under the project root, by extension, then MIME type, then shebang, minus whatever ci/shfmt-wrapper.conf excludes.
  • --conf <path> replaces discovery with an exact, fixed list - a test fixture's own throwaway scope, deterministic on purpose.
  • --exclude <path> swaps in a different exclude file without changing how discovery itself works.
  • --githook-precommit narrows discovery's own result to whatever intersects the staged diff - nothing staged that matches means nothing to check, not a failure.
  • --write is the only mode that changes a file: shfmt -i2 -w in place, for a developer to self-fix. Never run by a gate automatically.
  • -h, --help prints this message and exits 0.

The part a bare "just run the linter" instruction cannot give you is tests/shfmt-wrapper/ - already-formatted, needs-reformatting, and unparseable are each a test script paired with an rc file holding the exit code that test is expected to return. A skill that checks other code is itself code, and code that goes unverified is exactly the gap this whole talk is about closing. Pre-commit hooks and the meta-skill that lints a skill's own structure are both coming up next - this page is only about the wrapper and its own test cases.