Getting it into your agent
It runs from inside its repository, so the clone comes first — what it calls does not travel with the file alone.
git clone --depth 1 https://github.com/kouroshez/coding-osnpx agentmods add skills/kouroshez/coding-os/hook-authoringWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/kouroshez/coding-os/hook-authoring)<a href="https://agentmods.dev/skills/kouroshez/coding-os/hook-authoring"><img src="https://agentmods.dev/badge/skills/kouroshez/coding-os/hook-authoring/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/kouroshez/coding-os/hook-authoring"><img src="https://agentmods.dev/badge/skills/kouroshez/coding-os/hook-authoring.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00105 | $0.02940 |
| Opus 5 | $0.00053 | $0.01470 |
| Sonnet 5 | $0.00021 | $0.00588 |
| Haiku 4.5 | $0.00011 | $0.00294 |
Grade A, and why
hook-authoring scanned grade A with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 5d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Runs shell commandslowCapability
Expected in a hook, worth knowing in a rule or an instructions file.
proc = subprocess.run( How it starts
The opening of the file, as written. The whole thing — 293 lines — stays where its author put it; the contents beside it link to each section on GitHub.
hook-authoring
Purpose: Every hook in src/core/hooks/ propagates via live symlinks to every consumer project that registers any adapter. A buggy hook breaks N projects at once. The same shape, every time, keeps the ~50 hooks coherent.
Read when: editing files matching:
src/core/hooks/*.sh— hook scripts.src/core/hooks/_helpers/*.py— Python helpers invoked by hooks.src/core/hooks/registry.yaml— the SSOT for hook registration.src/adapters/<id>/adapter.yaml(hook_capabilitiesblock) — runtime capability filter.
Skip when: editing hook tests, runtime presence files in .coding-os/, generated adapter templates.
The Three Hard Contracts
Every hook MUST satisfy:
1. Source cos-env.sh (Rule 3)
The first non-comment lines of every hook:
#!/usr/bin/env bash
# What this hook does, one line.
set -euo pipefail
source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
cos-env.sh exports $COS_STATE_DIR, $COS_AGENT, $COS_AGENT_DIR, $COS_DB_PATH, etc. Without it, the hook will reach for hardcoded .claude/ paths and break on Codex/Cursor.
2. Never hardcode .claude/ (Rule 1, P2)
# WRONG
state_file=".claude/state/something"
# RIGHT
state_file="$COS_AGENT_DIR/something"
# or, if it's session-shared across agents:
state_file="$COS_STATE_DIR/something"
The block-hardcoded-literals.sh hook audits the diff and blocks .claude/ literals in src/core/**.
3. Register in registry.yaml (Rule 10, SSOT)
A new hook file is invisible until registered. Add an entry to src/core/hooks/registry.yaml:
- id: my-new-hook
script: my-new-hook.sh
event: PreToolUse # PreToolUse | PostToolUse | UserPromptSubmit | Stop | SessionStart | PostToolUseFailure | SubagentStart | SubagentStop
matcher: "Write|Edit" # tool matcher (event-specific) — empty = match-all where allowed
phase: gate # gate | observation | enforcement | telemetry
category: governance # documentation | governance | safety | telemetry | task | skill | graph | ...
description: "One line — what the hook does."
blocking: true # exit 2 blocks the tool call; false = soft warn only
adapters: ["claude", "codex", "cursor"] # which adapters to render this hook into
What ships with it
2 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 5d ago First seen · 293 lines · 105 tokens per session scan A fbe1ef3853db
hook-authoring is a skill published in the GitHub repository kouroshez/coding-os (6 stars, last pushed yesterday), licensed Apache-2.0. It adds 105 tokens to every session and 2,940 once invoked, about $0.0005 per session on Opus 5. A static security scan graded it A with 1 finding (runs shell commands). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-03.
Other skills, from other repositories
potpie-graph
Use when the task can read or write the project-memory graph through the potpie CLI: discover the contract with graph catalog, read named views with graph read, resolve entity identity with graph search-entities, create validated plans with graph propose, commit plans with graph commit --verify, inspect quality with…
potpie-source-ingestion
Use when the user explicitly asks to ingest, refresh, or deeply understand a repository, PR, issue, ticket, runbook, incident report, document, or web link into Potpie. The harness performs todo-driven discovery, uses local/GitHub/integration tools and read-only subagents when available, builds evidence-backed…
potpie-repo-baseline
Use when establishing, refreshing, or deeply understanding a repository's baseline memory in Potpie: purpose, application type, features, services/modules, environments, deploy shape, dependencies, API contracts, datastores, integrations, ownership, and explicit preferences. The harness reads authored and…
graph-mutation-plan
Cookbook for composing an applygraphmutations plan — stable entitykey patterns, the canonical label/edge vocabulary, evidence/invalidation/confidence discipline, and a worked example. Load this when building a non-trivial mutation plan.
potpie-cli
Use when the task is centered on running, explaining, configuring, or troubleshooting the potpie command: doctor, login, pot management, source registration, search, graph workbench reads/writes, and pot scope behavior.
potpie-change-timeline
Use when an agent needs recent or historical change context: what changed recently, regressions, merged PRs, tickets, docs, incidents, deployments, releases, and source-history ingestion.