smartgift-claude-skills/plugins/dev/skills/sg-md-writing/SKILL.md

name, description

name

description

sg-md-writing

Use whenever a project's agent knowledge needs writing or upkeep. That covers creating, reviewing, tightening or re-syncing CLAUDE.md / AGENTS.md / .claude/rules files (including right after a code change moves a path, renames a symbol, or retires a rule they mention), deciding where a new rule should live, and writing a Claude Code skill (SKILL.md), a subagent definition, or a hook that enforces a rule.

Maintaining project knowledge (CLAUDE.md, AGENTS.md, rules, skills, subagents)

These files are the project's memory for every agent that works in it. Their job is to hand the next agent the facts it cannot get from the code, in the place where the agent will meet them, at the lowest token cost. Keep them true, small and well placed. A stale line is worse than a missing one, because the model trusts it.

What earns a line

Write what the model cannot infer by reading the code:

• Intent and invariants, each with its consequence. "Money is stored as integer đồng — floats drift the ledger."
• Deliberate oddities. "LotteryService is deterministic on purpose — do not 'fix' it to rand()." Without the line, a model will "fix" it.
• The reuse map. For each existing feature: where its backend, UI and tables live, how to check it works, and the extension point new work must use ("new widget kinds extend the widgets table + WidgetKind enum, never a parallel table"). No model infers which existing structure already covers a feature. Without this map, agents build parallel ones.
• Commands that are not obvious from the files, and traps (an env var a test needs, a port shared with prod).

Leave out descriptions the model can read for itself (registration order, folder listings, config keys), generic virtues, step-by-step recipes and code to paste. You are not reviewing the code. A file records the owner's decisions, never your opinion of the code. Turning "this should be extracted" into a rule makes a model execute it. Record intent only when the user confirmed it, or when a comment or construct proves it is deliberate. Raise everything else separately.

Write each rule as a plain imperative with its reason. Write so that the weakest model that will read the file (a Haiku-class or small local model) has every fact it needs: locations, contracts, the verify command. Clarity carries that, not capitals. Keep emphasis for the one rule a model demonstrably keeps breaking. A rule that must never break belongs in a hook or a permission rule, with the .md line as context. A PreToolUse hook blocks with exit 2. Exit 1 does not block.

Where a line lives (load cost)

Place	Loads	Use for
Root CLAUDE.md / AGENTS.md	Every session, every turn	Project identity, routing table to module files, cross-cutting rules, commands, the two standing rules below
.claude/rules/*.md with paths: frontmatter	When Claude reads a matching file	A rule tied to some paths (src/webhooks/**)
<module>/CLAUDE.md	When Claude reads files in that folder	A module's reuse map, patterns and gotchas
.claude/rules/*.md without paths:	Every session, like root	Rarely. Prefer root, or add paths:
A skill	Its description every session, its body on use	A procedure needed only sometimes
docs/… named by a plain path ("read when …")	Only when the agent opens it	Long background for humans and agents

@path imports expand at launch. They organise text but do not save context. Root grows only with what every task needs. A rule that applies to some paths goes to a path-scoped rule or a module file, even when the user says "add it to CLAUDE.md". Say where you put it and why.

Every root file carries two standing rules:

• Check before create. "Before creating any table, function, class, config key, file or endpoint, search the reuse map and grep for something with the same purpose. Extend it if it exists."
• Sync. "A change that makes a statement in any .md wrong (moved path, renamed symbol, new or changed extension point, retired rule) updates that .md in the same change." Root also carries a Last synced: <commit or date> marker. It is the baseline for the next sync.

Modes

Sync (after a code change; the most common). Grep the .md set for every old name and path the change touched. Check each hit against the current code, then fix exactly the lines the change made wrong, in the same change-set. Leave every other line as it is: no rewording, no new rules. Bump Last synced. Report one line per file changed. Do not stop for confirmation. Ask only about intent the code cannot settle (one question, with your recommended answer first).

Add a rule. Find whether a rule on the same point already exists. Update it rather than add a second one, and settle any contradiction. Place the rule by the table above. Condense it to the constraint plus its reason.

Review or tighten. Look for:

• Contradictory rules.
• Emphasis on everything (so emphasis means nothing).
• "Think step by step" lines. Effort and thinking settings control that.
• Imports that were meant to save context.
• Hard rules that belong in a hook.
• Stale paths or symbols (check each against the code).
• Module detail sitting in root.
• Descriptions of the code instead of constraints on it.

Propose each fix with its reason.

Create or overhaul. Work in this order:

1. Draft the raw facts. Use /init for root, or read the tree. For a large tree, run one Explore subagent per module, in parallel.
2. Investigate before asking. Form your own guess for every intent candidate and hunt down the reuse map.
3. Ask only what the code cannot tell you: deliberate oddities, what breaks silently, what must never be done, commands. Put these in one AskUserQuestion round with recommended answers, in the user's language.
4. Write root plus a module file for each module that has its own rules or reuse map. A folder with nothing non-inferable gets no file.
5. Show the file list with one line per file, then write.

If a set already exists, patch it. A rewrite loses intent the owner already confirmed.

Check.

• After a sync: grep that no old name or path is left.
• After a create or overhaul: give a Haiku-class subagent a realistic one-line feature request and only "read CLAUDE.md from the root and follow it". Ask for a plan only.
  • It must land in the right module and reuse the named extension point.
  • If it doesn't, a line is missing or unclear. Fix the file and run the check again.

Skills

• description says WHEN to load the skill: the situations, and the words a user would actually type. It is not a summary of the steps, because a description that summarises the workflow gets followed instead of the body. Put the main trigger first.
• The body states the goal, the constraints and the finish line, then lets the agent adapt. Keep a fixed sequence only where order is load-bearing, and say why.
• Always include a ## Gotchas section, even if it holds one starter entry. It grows from real failures.
• disable-model-invocation: true for side effects (deploy, commit, send).
• allowed-tools pre-approves tools. It does not restrict them, so list a pattern (Bash(make deploy-staging)), never bare Bash. disallowed-tools restricts.
• paths limits activation to matching files.
• Long reference goes in references/ and code in scripts/. Point to each from SKILL.md with a "symptom → file" line. Keep SKILL.md under 500 lines.
• Leave out what the model does anyway.

Subagents

• Push back on a subagent whose only job is to run tests or a build. It summarises away the failure output the main agent needs. Run checks in the main thread, or have the agent return the raw failing output.
• Every definition needs a concrete OUTPUT FORMAT and an Obstacles part in that output (workarounds, environment quirks, dead ends), so the caller doesn't rediscover them.
• Give it the fewest tools that work: a researcher gets Read/Glob/Grep, and a reviewer gets no Edit/Write.
• No "You are an expert X" persona. The one-line description also steers what the caller asks for.
• Delegate work whose intermediate steps the main thread doesn't need (search, broad reading, independent review). Avoid chains of dependent agents.
• A subagent sees a skill only if the skill is listed in its skills: field. A dispatch prompt that depends on a module file should name that file.

Gotchas

• Root bloat creeps in through "add this to CLAUDE.md" requests. Root is a map, not a store. A root file over a few KB is a sign that module detail belongs elsewhere.
• Naming a smell ("duplicated in two places") without "deliberate — do not change" reads as an invitation to refactor.
• Anchor rules to stable symbols (class, function, table names), not line numbers. Line numbers drift.
• When the user pastes the file and the change instead of giving you a repo, work from what they gave. Deliver the update, and say in one line what you could not check. Do not ask them for the repo.