Recipes

Each recipe uses the checker at skills/everwrite/scripts/tells.py. Where your copy of the skill lives elsewhere (a plugin cache, ~/.copilot/skills/everwrite), put that path in its place.

A pre-commit hook

This hook refuses a commit while a staged markdown file has a strong tell. Save it as .git/hooks/pre-commit and make it executable:

#!/bin/sh
# .git/hooks/pre-commit: refuse a commit while a staged markdown file has a strong tell
files=$(git diff --cached --name-only --diff-filter=ACM -- '*.md')
[ -z "$files" ] && exit 0
python skills/everwrite/scripts/tells.py $files || {
  echo "everwrite: fix the strong tells above, then commit again"
  exit 1
}

With draft.md from Home staged, the hook prints:

$ sh hook.sh
draft.md:3: strong inflation: 'marks a pivotal shift' (state the fact)
draft.md:3: strong residue: 'excited to announce' (say it directly)
draft.md:3: weak vocabulary: 'pivotal' (plain word or cut; never swap for another listed word)
draft.md:4: strong contrast: "It's not just faster, it's" (state the second half directly)
draft.md:4: strong residue: 'Let me know if' (delete the chat wrapper)
tells: 4 strong, 1 weak, 28 words, 1 file(s)
everwrite: fix the strong tells above, then commit again
$ echo $?
1

That run called the hook directly in a scratch repository with the file staged; a real git commit was not run. The unquoted $files splits on spaces, so file names with spaces need a different loop. git commit --no-verify skips the hook.

A CI step

The everwrite repository checks its own prose in CI with the same two commands its developers run (see Development). In another repository, with the skill folder copied in, one step is enough, and a strong hit fails the job because the checker exits 1. The step looks like this.

      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: python skills/everwrite/scripts/tells.py README.md docs

This YAML was not run for this wiki. The everwrite repository's own workflow, .github/workflows/tests.yml, runs the checker the same way on Ubuntu, macOS and Windows.

Only the counts, from JSON

$ python skills/everwrite/scripts/tells.py --json draft.md | python -c "import json,sys; print(json.load(sys.stdin)['summary'])"
{'strong': 4, 'weak': 1, 'words': 28, 'files': 1}

The skill's own notes recommend --json piped to a filter when only one category matters, since the agent then reads a few lines in place of the whole report.

Text that is not in a file

Pipe it in with - as the path, as on Commands. That suits a chat reply or an email draft that never lands in a file; the skill's own tests checked agent replies the same way.

Quoting tells on purpose

A style guide that lists phrases to avoid would fail its own check. Put the examples between lines holding only <!-- tells: off --> and <!-- tells: on -->:

Avoid openers like these:

<!-- tells: off -->
- I hope this helps!
- Let's dive in.
<!-- tells: on -->

The rest of the page is checked.

$ python skills/everwrite/scripts/tells.py style.md
tells: 0 strong, 0 weak, 11 words, 1 file(s)

The markers count only when each is the whole line. Mentioned inside a sentence or in inline code, they change nothing.

GitHub wiki pages

Run the checker with --wiki over the wiki's working copy so a first heading that repeats the page title is caught. This wiki was checked that way before each push:

python skills/everwrite/scripts/tells.py --wiki ../everwrite.wiki

The sidebar and footer (_Sidebar.md, _Footer.md) are still checked for everything else.