m-hosseinpour/agent-skills

trimming-project-instructions

Use when a project's instruction file — CLAUDE.md, AGENTS.md or whatever plays that role — has grown past what a session can hold, or when asked to shrink, split or reorganize one.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/m-hosseinpour/agent-skills --skill trimming-project-instructions

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

Trimming Project Instructions

A project instruction file is loaded at the start of every session in that project. Its length is a tax paid there, on every task, whether or not the task touches the area a section covers.

Core principle: every section is either a verdict — a rule, a decision, a "do not re-open" — or evidence: how the verdict was reached. The verdict stays, with the shortest warrant that stops it being re-opened. The evidence — the gates, the measurements, the dates, the sequence — moves to a document.

The one question

Is this the verdict, or the evidence for it?

Adding without asking it is how the file grows. Trimming without asking it is how a rule disappears. Most sections are half-live by construction — a durable head and a narrative tail — so the work is splitting them, not relocating them whole.

This is not the global file's problem. There the destination is a skill, which loads on a trigger. Here the destination is a document, which nothing loads — so the pointer is the trigger, and a moved rule nothing points at is a rule that gets re-derived. (For the global tier, see curating-global-instructions.)

The pointer rule

A pointer names the trigger, never a bare "see Y". "Before touching X, read Y" survives; "see Y" does not — the reader has no way to know they are in the situation Y covers.

Mechanics

Measure first. Count characters per section, before and after. A section that "feels long" is not a measurement, and a total that moved without a per-section number cannot be reported.

Extract mechanically. Move text by line range or marker match with a script, never by retyping — thirty thousand characters retyped is thirty thousand chances to drop a clause.

Verify every move. Grep a distinctive sentence from each moved block in its destination. After a restructure, compare every substantive line of the old file against the new one and explain each absence.

One destination per area, and a table in the instruction file mapping each file to what it holds — that table is how a later session finds the evidence without reading the whole directory.

Two operations, not one

Splitting is the per-section move above. Regrouping is the other, and it is worth doing deliberately: a file that grew a section at a time is organised by when each thing was written, not by what a session is looking for. That is how one heading ends up holding three unrelated concerns, how two headings end up holding the same kind of thing, and how a history comes to read as a rulebook. Group by what a session is looking for — what the project is, what is judged, what exists, what is decided, the rules, the settled work, the operations, the record map. Regrouping is also what surfaces the defects, because moving a section is when a pointer breaks.

Where to stop

The floor is where every remaining line is a rule, an invariant or a decided seam. Past it, each character removed costs a rule, and a lost rule is not paid back by a shorter file. When a pass moves only a few hundred characters and every candidate left is a rule's own warrant, stop and say so — reporting the floor is the honest end of this work, not a failure to finish it.

The defect class to hunt: dangling pointers

A move breaks four things, and no compiler catches any of them:

  1. A directional pointer that no longer points the right way — "the section below" after the section moved above.
  2. A pointer to a heading the move deleted.
  3. A cross-reference inside a moved block* that named its old neighbourhood — "removed above", "as noted earlier".
  4. An abbreviation or section number whose defining sentence was compressed away — "§5d", "the ladder", "the second form".

Hunt all four deliberately after the pass; they are the failures this work actually produces.

Do not weaken while compressing

A "never" can become a "prefer", a condition can drop, a scope can narrow — with no bullet deleted. Check each prohibition by name after the pass, and have an independent reader check the full diff when the change could weaken important rules. For small edits, compare the affected sections and verify the moved content directly.

Common mistakes

MistakeFix
Trimming by feel, or toward a target percentageMeasure per section; report the numbers
Deleting a rule because a document "covers that area"Read the document — areas are not contents
Moving evidence and leaving no pointerName the trigger, or do not move it
Retyping moved proseExtract it mechanically and verify it landed
Trusting the author's own read of the compressionDispatch a reviewer against the whole diff
aus demselben Repository

Weitere Skills

Alle Skills
m-hosseinpour
Community

curating-global-instructions

Use when adding to, trimming or reorganizing the instruction file loaded into every session whatever the project — the global CLAUDE.md, AGENTS.md, or whatever plays that role — or when it has grown past what a session can hold.

Installationen / 1h
2
GitHub Stars
0
Aktualisiert
15. Nov.
m-hosseinpour
Community

designing-persian-rtl-web-ui

Use when building, changing, or checking a Persian (Farsi) web interface — including right-to-left layout, typography, UI copy, numerals, responsive behavior, or dark mode — and before calling Persian UI work done. Not for RTL-only work in non-Persian interfaces.

Installationen / 1h
2
GitHub Stars
0
Aktualisiert
15. Nov.
m-hosseinpour
Community

dispatching-parallel-agents

Use when delegation is available and allowed and a task has multiple substantial workstreams that may be independent, when parallel agent work is requested, or before running a subagent alongside your own work or other subagents. Not for small multi-step tasks, parallel tool calls, or one delegate you will simply wait for.

Installationen / 1h
2
GitHub Stars
0
Aktualisiert
15. Nov.
m-hosseinpour
Community

research-with-evidence

Use when researching a question across multiple sources, doing in-depth web research, comparing options using external evidence, investigating conflicting claims, or checking the substantive claims and sources of a research report. Not for a simple factual lookup, explanation from already-sufficient evidence, translation or editing without fact-checking, code-change review, or diagnosing a concrete software failure.

Installationen / 1h
2
GitHub Stars
0
Aktualisiert
15. Nov.