Skip to content
Back to search

style-guide

Coding, documentation and writing style as rules and agent skills

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/muhlba91/style-guide with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/muhlba91/style-guide'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/muhlba91--style-guide/badge.svg)](/listings/muhlba91--style-guide)

HTML

<a href="/listings/muhlba91--style-guide"><img src="/api/listings/muhlba91--style-guide/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

make install

This links every skill into `~/.claude/skills` and `~/.agents/skills` and needs only bash. Set `STYLE_GUIDE_SKILL_DIRS` (space separated) to use other folders. A link that points elsewhere is left alone and reported.

The links point into this checkout. Keep it in place and run `make install` again after moving it. Do not copy the skill folders: a skill finds the guide by walking up from its link to `AGENTS.md` and stops with an error when there is none. Update with `git pull`, uninstall by removing the `style-*` links.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 117 lines
  1. # Style Guide
  2. [![License](https://img.shields.io/github/license/muhlba91/style-guide?style=for-the-badge)](LICENSE.md)
  3. [![Build status](https://img.shields.io/github/actions/workflow/status/muhlba91/style-guide/verify.yml?style=for-the-badge)](https://github.com/muhlba91/style-guide/actions/workflows/verify.yml)
  4. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/muhlba91/style-guide/badge?style=for-the-badge)](https://scorecard.dev/viewer/?uri=github.com/muhlba91/style-guide)
  5. This repository contains the owner's coding, documentation and writing style as rules with evidence, and skills that let agents write in the style, review against it, and keep it current.
  6. ---
  7. ## Requirements
  8. - [mise](https://mise.jdx.dev)
  9. ## Layout
  10. | Path | Content |
  11. | --- | --- |
  12. | `AGENTS.md`, `CLAUDE.md` | Working rules for agents. `CLAUDE.md` links to `AGENTS.md`. |
  13. | `common/principles/` | Rules across languages and artifacts. |
  14. | `common/languages/` | Deltas per language or file type. |
  15. | `common/writing/` | README, runbook, prose, commit, PR and issue text, email. |
  16. | `common/evidence/` | Method, weighting and sources behind the rules. |
  17. | `common/digest/` | Generated lean digests of the rules, read by the write and review skills (`make digest`). |
  18. | `common/skills/` | The skills `style-write`, `style-review`, `style-update`, `style-audit`. |
  19. | `.agents/skills/`, `.claude/skills` | Relative links to every skill (`make skills`). |
  20. | `OPEN-QUESTIONS.md` | Decisions still open. |
  21. | `CHANGELOG.md` | One line per rule change. |
  22. | `common/retired.txt` | Retired rule IDs, never reused. |
  23. | `mise.toml`, `mise.lock`, `.pre-commit-config.yaml`, `.conform.yaml`, `.markdownlint.yaml`, `.yamllint.yml` | Pinned tools, hooks and linter configs. |
  24. | `.github/`, `renovate.json` | CI workflows and Renovate. |
  25. | `scripts/`, `tests/`, `Makefile` | Quality gate (`make check`) and installer. |
  26. | `LICENSE.md` | AGPL-3.0. |
  27. | `llms.txt` | Machine-readable index. |
  28. | `work/` | Gitignored scratch and audit reports. |
  29. ## Rules
  30. Rule format, strength and status: see `AGENTS.md`. The rules cover Go, Pulumi, Python, shell, Kubernetes YAML, GitHub Actions, Renovate, mise, Nix, Typst, Makefiles, container, DNS and Home Assistant configuration, READMEs, runbooks, docs, commit messages, PR and issue text and email. This is a personal style guide: fork it and make it yours by changing the rules.
  31. To change a rule, ask `style-update`, or edit the rule file, run `make digest` and `make check`, and add a line to `CHANGELOG.md`. Never reuse a retired ID.
  32. ## Skills
  33. | Skill | Use |
  34. | --- | --- |
  35. | `style-write` | Write or edit code, docs, commits, PR text or email in the style. |
  36. | `style-review` | Review a change against the rules and report findings with rule IDs. |
  37. | `style-update` | Change the rules from feedback or new evidence, after the owner approves. |
  38. | `style-audit` | Audit the guide itself and test it on held-out work. |
  39. The loop: write, review, collect the owner's corrections, update, audit.
  40. ### Install
  41. ```bash
  42. make install
  43. ```
  44. This links every skill into `~/.claude/skills` and `~/.agents/skills` and needs only bash. Set `STYLE_GUIDE_SKILL_DIRS` (space separated) to use other folders. A link that points elsewhere is left alone and reported.
  45. The links point into this checkout. Keep it in place and run `make install` again after moving it. Do not copy the skill folders: a skill finds the guide by walking up from its link to `AGENTS.md` and stops with an error when there is none. Update with `git pull`, uninstall by removing the `style-*` links.
  46. ### Use
  47. Name the skill in the prompt:
  48. ```text
  49. /style-write add a retry option and commit it
  50. /style-review
  51. /style-update this finding is wrong, the rule should say X
  52. /style-audit
  53. ```
  54. - Agents without slash commands: ask for the skill by name, or link the skills into the folder that agent reads (`STYLE_GUIDE_SKILL_DIRS`) and point it at `AGENTS.md`.
  55. - The skills also trigger from their descriptions. That is not guaranteed and was not tested with installed skills.
  56. - A subagent does not inherit installed skills: give it the absolute path of `common/skills/style-write/SKILL.md` in this checkout.
  57. - Order of precedence: the task instruction, then the target repository's own rules, then this guide.
  58. - Optional global instruction for `~/.claude/CLAUDE.md` or the agent's global file. It costs about 100 tokens per session, loads the skill only for substantial writing and is untested as a trigger. The commit line works even when the skill does not load (COMMIT-17). Without it, call the skills by hand.
  59. ```text
  60. Use the style-write skill before writing docs, PR text or an email, creating a file, or adding a new function or resource; skip it for questions and small edits that follow the surrounding code.
  61. Commits: Conventional Commits, lowercase imperative, 3 to 6 words (100 characters at most), no prose body, scopes only ci, deps and release (never as a type), and no attribution (no Co-Authored-By, no Signed-off-by, no "Generated with").
  62. ```
  63. ### Model Choice
  64. Result of the first evaluation (2026-11, one to two runs per case, summary in `common/evidence/README.md`):
  65. | Work | Model class |
  66. | --- | --- |
  67. | New repositories, multi-file changes, anything without a template next to it | Sonnet |
  68. | Small, well-scoped changes next to existing files, followed by a `style-review` pass | Haiku, at about a tenth of the cost |
  69. | Reviewing a small change with `style-review` | Haiku: it caught a planted violation and stayed quiet on clean changes, but may add a suggestion your own practice contradicts |
  70. | Full audit with `style-audit` | A stronger model than the one that changed the rules |
  71. | Any writing without the skill | Avoid: every such run added the forbidden attribution trailer, and designs differed where no template was nearby |
  72. Haiku with the skill came close to Sonnet on small changes. On whole new repositories its runs varied more and one missed a file the program needs, so review those.
  73. ### Token Load
  74. - `style-write` is small (a few hundred tokens), `core.md` about two thousand, each digest a few hundred to under two thousand. A task loads a few thousand tokens of the guide, never the full rules.
  75. - Installed skills add their descriptions to every session (a couple of hundred tokens in total).
  76. - In the evaluation, a skilled run used about the same to 30 percent more tokens than an unskilled one. A `style-review` pass of a small change cost about as much again.
  77. ---
  78. ## Continuous Integration and Automations
  79. - GitHub Actions: conform on commit messages, lint, and the rule, digest and test checks (`.github/workflows/verify.yml`), plus dependency review, CodeQL and OpenSSF Scorecard.
  80. - Renovate Bot: keeps actions, pre-commit hooks and mise tools current (`renovate.json`).
  81. ## Development
  82. Tool versions (mise, Python, Node, shellcheck, yamllint, markdownlint) are managed with mise: run `mise trust` and `mise install` once, then use `make check` for the gates of CI (conform runs on commit messages instead), `make digest` after a rule change and `make help` for the rest.
  83. Without mise, put python3, shellcheck, yamllint and markdownlint-cli2 on the PATH.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.