DEV Community

ZEUS LAB
ZEUS LAB

Posted on Edited on

A rule file asks, a hook refuses: CLAUDE.md, AGENTS.md, SKILL.md and what our own log shows

An instruction file is a request. A hook is a rule. Coding agents now read several kinds of Markdown files, and it helps to be clear about which ones can actually stop something.

Figures below come from our own event log between 2026-11-12 10:35 and 2026-11-14 02:50 UTC: 1,924 events, of which 1,431 tool calls. They describe our setup only; they are not a rate for anyone else's.

Three files that ask

CLAUDE.md and AGENTS.md are project guidance. The agent reads them and, most of the time, follows them. AGENTS.md is one of the founding projects of the Agentic AI Foundation under the Linux Foundation, alongside MCP; Claude Code reads CLAUDE.md.

SKILL.md is the Agent Skills format published at agentskills.io: a folder with a SKILL.md whose YAML frontmatter carries a name and a description. The agent loads the body when it decides the skill fits the task. That makes it good for how to do a job, and it still asks rather than enforces.

All three are text in the context window. In a long session they compete with everything else the agent has read. In our own sessions, we saw a standing instruction to reply in one language dropped once a long conversation had been summarised.

One thing that refuses

A Claude Code PreToolUse hook runs before the tool call and can end it with exit code 2: the call does not run, and the agent receives the message on stderr. The hook below is from our MIT starter and refuses one thing: a commit or push that skips the commit checks.

import json
import re
import sys

SKIP_FLAG = "--no-" + "verify"
RULE = re.compile(r"git\s+(commit|push)\b[^\n;|&]*" + re.escape(SKIP_FLAG))


def main() -> int:
    try:
        data = json.loads(sys.stdin.read() or "{}")
        if data.get("tool_name") == "Bash":
            command = str((data.get("tool_input") or {}).get("command", ""))
            if RULE.search(command):
                sys.stderr.write("guard: refused — this command skips the commit checks. Fix the cause instead.\n")
                return 2
    except Exception:
        return 0
    return 0


if __name__ == "__main__":
    sys.exit(main())
Enter fullscreen mode Exit fullscreen mode

It is a text match: it does not catch the short -n form, and it can match the phrase inside an echoed string. It fails open on purpose, so an error inside the hook lets the call through.

What our log counted

Event (2026-11-12 10:35 → 2026-11-14 02:50 UTC) Count
Tool calls logged 1,431
Calls refused by the guard hook 2
— touching a metered-key variable 1
— skipping the commit checks 1
Leak-check gate runs before commit or publish 125
— runs that stopped (exit 1) 6

Two refusals in 1,431 calls is a small number; both were calls the hook was written to refuse. The six stopped runs were fixed and run again before anything was published.

Keep the SKILL.md honest

Skills travel between tools, and a malformed one may fail to load. The format's rules are short enough to check in plain Python:

import re
NAME = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")

def check(folder_name, fm):
    errs = []
    name, desc = fm.get("name", ""), fm.get("description", "")
    if not (1 <= len(name) <= 64 and NAME.match(name)):
        errs.append("name: 1-64 of a-z, 0-9 and single hyphens")
    if name != folder_name:
        errs.append("name must match the folder")
    if not 1 <= len(desc) <= 1024:
        errs.append("description: 1-1024 characters")
    return errs
Enter fullscreen mode Exit fullscreen mode

We run a fuller version on every product ZIP before release; it reads the frontmatter, checks compatibility length and the folder name, and blocks the release on any problem.

Read a skill before you install it

A SKILL.md or an MCP config from someone else is code-adjacent text that your agent will act on. Before installing one, it is worth looking for environment-variable references, URLs that are not local, network commands, and anything that decodes and pipes into a shell. Our free browser tool has a review mode that highlights exactly those, without masking them, so you can judge each one. Many are legitimate; the point is to see them.

The short version

  • Use CLAUDE.md or AGENTS.md for what the project expects.
  • Use SKILL.md for how to do a specific job, and validate it.
  • Use a hook or a gate for anything that must not happen.

Free, processed in the page with no network connection: https://zero-trace-ship-kit.zeus-lab-global.workers.dev/paste-guard/?utm_source=devto

Every kit, with the SKILL.md and AGENTS.md files included and launch prices until 30 November 2026 or until a code's 100 uses run out: https://zero-trace-ship-kit.zeus-lab-global.workers.dev/bfcm/?utm_source=devto

The kit that puts this check on commit and push, on one page: https://zero-trace-ship-kit.zeus-lab-global.workers.dev/go/ship/?utm_source=devto


Disclosure: this article was drafted with AI assistance (Claude) and checked against the measured results and the published files. Product links lead to our own paid kits.

Top comments (0)