engine-comments

engine-comments is a skill for Claude Code from IgnacioMarin402/spec-flow-plugin. It costs 74 tokens per session (660 once invoked), scanned A, original, MIT.

A guide for deciding where explanations belong in an engine's codebase: beside code as invariants, in commit messages as transitions, or in decision records as design choices.

In plain words
What is it for?
Writing or editing comments and file headers in hooks, scripts, commands, or agents, and deciding when lengthy headers should be moved.
Why use it?
It prevents comments from becoming overloaded while keeping important reasoning available where future maintainers need it.

Skill for Claude Code

Written for Claude Code: installed under .claude/. Also seen: mentions subagents.

Part of the spec-flow plugin — 2 skills, 4 commands, 5 agents, 7 hooks shipped together

Good fit Writing or editing comments and file headers in hooks, scripts, commands, or agents, and deciding when lengthy headers should be moved.

Compare 6 skills from other repositories ↓
Install with agentmods
npx agentmods add skills/ignaciomarin402/spec-flow-plugin/engine-comments
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent
npx skills add IgnacioMarin402/spec-flow-plugin --skill engine-comments
Clone the repo
git clone --depth 1 https://github.com/IgnacioMarin402/spec-flow-plugin

Made for: Claude Code.

Or install spec-flow, the plugin that ships this one along with the rest of its 2 skills, 4 commands, 5 agents, 7 hooks.

Wrote 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.

agentmods badge for engine-comments

README.md
[![agentmods](https://agentmods.dev/badge/skills/ignaciomarin402/spec-flow-plugin/engine-comments/github.svg)](https://agentmods.dev/skills/ignaciomarin402/spec-flow-plugin/engine-comments)
Your own site
<a href="https://agentmods.dev/skills/ignaciomarin402/spec-flow-plugin/engine-comments"><img src="https://agentmods.dev/badge/skills/ignaciomarin402/spec-flow-plugin/engine-comments/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.

agentmods 80×15 button for engine-comments

Your own site · 80×15
<a href="https://agentmods.dev/skills/ignaciomarin402/spec-flow-plugin/engine-comments"><img src="https://agentmods.dev/badge/skills/ignaciomarin402/spec-flow-plugin/engine-comments.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 74 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 660 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.
Origin original No closer match found in the catalogue.
Token cost

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.

ModelPer sessionOnce invoked
Fable 5.1 $0.00074 $0.00660
Opus 5.5 $0.00030 $0.00264
Sonnet 5.5 $0.00015 $0.00132
Haiku 4.5 $0.00007 $0.00066

Measured 25d ago against content hash 28b70aad7710, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

engine-comments scanned grade A with 0 findings 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 25d 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.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.claude/skills/engine-comments/SKILL.md · 55 lines

How it starts

The opening of the file, as written. The whole thing — 55 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Where reasoning goes in this engine

Before writing a comment, decide which of three things you are writing.

1. Invariant — why this line must be this way → beside the code

Read exactly when someone is about to undo it, and whoever changes the line already has the file open. Write one when the code would look arbitrary, or improvable, to a competent reader who does not know what it defends against. Keep it to what they need to not break it — not the story of how it was found.

// AFTER the phase guard: this hook fires on every subagent spawn in every
// repository the user opens, so a check ahead of it would deny unrelated agents.

2. Transition — what the code used to be → the commit message

"This used to match it(...), then Python arrived" is a commit message that leaked into the source. Git holds it with the diff attached, and it cannot drift. Test: would the sentence read as history to someone who never saw the old version? Then it goes in the commit body. Recover one with git log -S, git log -L or git blame -L.

One narrow exception: when an old shape is a trap someone is likely to reintroduce, a single line naming it is an invariant — // not \b-delimited: Go and pytest glue ids to their neighbours.

3. Decision — why the system has this shape → decisions/

Spans files and has refused alternatives, which is why it ends up copied into several headers and drifting between them. Write it once as a dated record in decisions/ and cite it from the code as see ADR-NNN (with the record's real number). scripts/decisions.mjs fails on a citation that does not resolve and on a record nobody cites. A record claims a moment, so it stays true after the decision is reversed; a reversal writes a new record.

Prose describing how the code works today belongs in none of these places.

Applying it to an existing header

Sort each paragraph into 1, 2 or 3. What is left should say what the file guarantees, what a reader must not break, and where the rest lives.

Read the full file on GitHub · 55 lines

Changes

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.

  1. 25d ago Changed · -85 lines 28b70aad7710
  2. 1mo ago First seen · 140 lines · 74 tokens per session scan A 779defbf39ab

Subscribe to this mod's changes

engine-comments is a skill published in the GitHub repository IgnacioMarin402/spec-flow-plugin (2 stars, last pushed 4d ago), licensed MIT. It adds 74 tokens to every session and 660 once invoked, about $0.0003 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

great_cto

Use when the CTO describes a feature, task, or project goal. Orchestrates the full SDLC pipeline automatically based on project type.

avelikiy/great_cto · 32 tokens

anti-patterns

Catalogue of known SDLC anti-patterns that greatcto agents must actively reject when reviewing architecture, plans, code, or post-mortems. Used by architect (pre-impl), pm (planning), senior-dev (impl), l3-support (post-incident).

avelikiy/great_cto · 59 tokens

cost-model

Standardized cost-estimation framework for greatcto plans. Forces explicit LLM cost, infra cost, human-supervision time, and the (defensible) human-equivalent comparison. Output format is parsable by the board's /api/cost path — must follow exactly.

avelikiy/great_cto · 59 tokens

stack-baseline

The pinned default technology stack for SMB Product-Builder products. One source of truth so the architect, app-scaffolder, auth-engineer, and senior-dev never re-decide the stack per build — they build ON it. Covers framework, ORM/DB, auth, UI, payments/email/SMS, files, jobs, testing, hosting, and observability…

avelikiy/great_cto · 126 tokens

deploy-landed

A deployment verification procedure that checks whether the intended code revision is actually running, its environment settings are present, and the product works. A deployment is the process of putting new software on a server or hosting platform.

avelikiy/great_cto · 103 tokens

hcom-spawn

An instruction set for starting and coordinating other coding agents through HCOM, a system for agents to communicate and work together. It covers choosing an agent, giving it a task, monitoring it, and ending the collaboration.

ouob-tw/LoopAgentTeams · 80 tokens