accelint-skill-prose

name	accelint-skill-prose
description	Use when creating, auditing, tightening, simplifying, polishing, or reviewing `SKILL.md` files, agent-skill instructions, `CLAUDE.md` or `AGENTS.md` guidance, or other behavior-defining prompt artifacts whose wording controls trigger coverage, workflow order, guardrails, approval semantics, or exact technical meaning. Prefer this skill over general prose editing when the job is to make wording clearer without changing behavior, including safe description rewrites, ambiguity audits, and edits that must preserve exact paths, commands, fields, or identifiers. Do not use it when the main task is broader content strategy, policy design, domain review, or ordinary prose cleanup with no behavior risk.
license	Apache-2.0
metadata	{"author":"accelint","version":"0.9.4"}

Skill Prose

Use this skill to edit behavior-defining prose without changing behavior.

Core contract

Use this skill for text whose wording controls behavior, not just tone. In these artifacts, wording controls when a skill triggers, what it promises, what order work happens in, and what must stay exact.

Write in plain, direct English. Do not treat skill prose like ordinary prose. A cleaner sentence is a bad edit if it changes behavior.

Make the prose easier to follow, easier to audit, and harder to misread while preserving:

• trigger coverage
• workflow semantics
• guardrail strength
• exact technical meaning

Keep one term for one concept. Do not rotate terms just to avoid repetition. In skill prose, stable terminology is part of the behavior contract.

Use compatible ideas from Simplified Technical English only for local, behavior-preserving clarity improvements that pass the Decision tests below, such as short explicit sentences, consistent terminology, active voice by default, and clear separation between instructions and explanation. Do not use these patterns to add qualifiers, explain intent, supply rationale, or reshape policy. Do not apply controlled-language rules mechanically if that would erase rationale, flatten scope, or weaken behavioral precision.

This skill extends general English editing with extra safety for:

• root SKILL.md files
• sibling AGENTS.md guidance files
• behavior-bearing references/*.md files
• frontmatter descriptions
• agent instructions
• prompt templates
• workflow guidance
• hard stops and guardrails
• exact technical references inside prose

Use assets/output-template.md for all outputs.

Behavioral drift

Behavioral drift is not limited to paths, fields, and quoted tokens. If a verb changes what an agent may do, when it may do it, or how strongly a rule applies, that verb is behavior-bearing. Preserve it, or replace it only with wording that keeps the same behavior.

Rationale is not filler by default. If a sentence explains why a guardrail exists, why a checkpoint matters, or what risk a timing rule prevents, preserve that rationale unless the user explicitly asked to change the policy rather than tighten the prose. Preserve rationale by retention or strict equivalence, not by elaboration. Do not introduce new harms, failure modes, usability claims, maintainability claims, robustness claims, workflow-stability judgments, or environment qualifiers unless the source already states them.

Qualitative execution cues are behavior-bearing when they act as hidden gates, fallback conditions, or permission slips. Words and phrases such as small, large, simple, complex, constrained environment, practical, impractical, reasonable, brittle, significant, materially, beneficial, if needed, when appropriate, and without reason can let the model self-justify behavior unless the surrounding text makes the condition operational enough to preserve the same branch. Do not preserve these cues by default just because they are already present. Do not treat a rewrite from one qualitative branch term to another as a real fix. For example, small, constrained, and brittle do not become operational just because they change to practical or impractical. In audit mode, flag these cues when they steer execution without an operational boundary. In rewrite mode, either remove them, replace them with source-supported operational conditions, or classify them as unresolved policy ambiguity if no lossless rewrite is possible.

Untouchables

Leave these exact unless the user explicitly asks to change them:

• tool names
• file names and paths
• commands and flags
• field names and keys
• identifiers
• slash-joined references
• inline code and code blocks
• quoted errors and logs
• examples that define scope or expected behavior

These are behavior anchors, not decorative prose.

What makes this different from general prose editing

Use this skill when wording itself controls behavior. In these artifacts, these elements often carry behavior rather than decoration:

• trigger phrases
• examples that define scope
• workflow order
• approval gates
• hard-stop wording
• file paths
• commands
• identifiers
• field names
• quoted text
• cross-references to other files or sections
• linked support files whose wording completes the rule, example set, or workflow

Do not simplify these casually.

Hard stops

• Never broaden trigger coverage silently.
• Never narrow trigger coverage silently.
• Never weaken a hard requirement into advice.
• Never reorder workflow steps when order affects behavior.
• Never paraphrase exact references just because the paraphrase sounds cleaner.
• Never remove an example if it defines scope, behavior, or edge-case coverage.
• Never return a polished rewrite that is behaviorally less safe than the source.
• Never slip a rewrite into audit-only mode.
• Never introduce new qualifiers, thresholds, fallback branches, environmental assumptions, or discretionary conditions unless the source already contains them or the user explicitly asked to add them.
• Never preserve qualitative gate wording by default when it creates a hidden branch, discretionary fallback, or self-justifying exception.
• Never treat one qualitative branch term as a safe replacement for another unless the source itself defines the replacement operationally.
• Never add new rationale, failure modes, usability claims, maintainability claims, robustness claims, or workflow-stability judgments unless the source already states them.
• Never convert a warning, rationale, note, or descriptive statement into a new gate, prerequisite, checkpoint, or branch unless the source already states that dependency explicitly.
• Never propagate stylistic preferences across files unless a concrete mismatch in trigger scope, workflow semantics, guardrail strength, exact references, or behavior-bearing terminology would otherwise remain.

Priority order

When goals conflict, use this order:

1. Preserve trigger intent and scope.
2. Preserve workflow semantics and approval logic.
3. Preserve guardrails and hard-stop strength.
4. Preserve exact technical references.
5. Improve clarity, consistency, and actionability.
6. Improve brevity.

Operating controls

Choose these controls before you edit. Do them in order.

1. Choose the output mode. This controls what you will deliver.
2. Choose the rewrite mode. This controls how far you may reshape the prose.

Do not reverse these steps. Keep them separate. Output mode controls the deliverable. Rewrite mode controls the rewrite scope.

Operating control 1: Choose the output mode

Output mode controls the deliverable, not the rewrite scope.

Audit only

Always include the consistent report from assets/output-template.md.

Use this mode when the user wants review, risk analysis, or a check for ambiguity, drift, or weak wording.

Do not rewrite the text unless the user explicitly asks for a rewrite.

Do not include replacement wording, "safer" rewrites, or suggested revised sentences in the deliverable. If you need to point to a safer pattern, describe the risk in principle instead of drafting substitute text.

In audit-only mode, do not draft replacement text. If the user explicitly asked for examples, quote the source and name the safer pattern without proposing substitute wording.

Rewrite only

Use this mode when the user wants cleaner final text directly.

Audit plus rewrite

Use this mode when the user wants both findings and a safer revision.

Operating control 2: Choose the rewrite mode

Choose the rewrite mode after the output mode.

For rewrite tasks, ask the user which rewrite mode they want unless the user already made the scope clear.

Offer these modes:

• mode=default — local rewrite by default.
• mode=strict — structural rewrite is allowed when needed.

For audit-only requests, you may proceed without asking for a rewrite mode. If the task expands into a rewrite, ask for the rewrite mode before you rewrite.

Operating control 3: Apply the rewrite mode

mode=default

Use this mode for narrow cleanup, exactness-preserving clarification, typo fixes, or local tightening.

Behavior:

• preserve the source structure unless the structure itself hides behavior
• preserve examples, labels, and section order when they already carry behavior
• prefer phrase-level and sentence-level repairs over reorganization
• prefer the smallest local rewrite that makes the rule easier to follow

mode=strict

Use this mode only when local edits cannot make the source behavior clear without structural reorganization, such as repeated ambiguity, mixed severity language, buried workflow logic, or unstable terminology.

Behavior:

• preserve behavior, but allow structural rewrite when the structure itself causes ambiguity
• separate instructions, rationale, warnings, and examples when that exposes existing logic more clearly without adding new policy
• normalize terminology more deliberately across the edited artifact set only when the source already treats the concepts as equivalent
• reorganize only as far as needed to make existing trigger scope, workflow order, and guardrail strength easier to follow without adding conditions, criteria, or decision tests not already stated or strictly implied by explicit dependencies in the source

Strict mode is not permission to broaden scope casually. In both modes, keep the smallest change that solves the real problem unless the user explicitly asked for a broader rewrite.

Operating control 4: Choose the artifact focus

Use these lenses when they match the text:

• Frontmatter description tightening — Use this focus when the text controls triggering. Treat the description as compact behavioral logic, not as a marketing blurb.
• Workflow or guardrail tightening — Use this focus when the prose defines step order, approval dependencies, decision points, safety limits, exact execution rules, or fallback conditions that need operational wording.

Before you edit

Before-you-edit step 1: Extract what must stay fixed

Do this before you tighten, reorder, or relabel anything.

First, normalize vocabulary for the concepts that matter. Pick one term for each repeated concept and keep it throughout the edit when the source already treats those terms as equivalent. Common clusters include trigger / invoke / activate, audit / review / analyze, field / key / property, and workflow-role terms such as stage / step / gate / checkpoint / branch / readiness check. Do not normalize two source terms into one if they may differ in permission, timing, scope, or workflow role.

Look for:

• the exact task or artifact scope
• explicit trigger phrases
• user-requested boundaries
• workflow order
• approval gates
• hard requirements
• paths, commands, identifiers, fields, keys, flags, and examples
• quoted wording that must stay exact
• qualitative wording that may act as a hidden gate, fallback condition, exception, or permission slip

If the request says to preserve trigger coverage, exact meaning, or specific tokens, raise the preservation threshold further.

Before-you-edit step 2: Define the artifact set when the task covers a skill folder

Requires: Complete Before-you-edit step 1.

Default to the root SKILL.md, sibling AGENTS.md if present, and behavior-bearing Markdown under references/. Add other linked instruction files when the root file depends on them for trigger scope, workflow order, guardrails, examples that define scope, or exact-reference meaning. Do not infer contract significance from perceived usefulness alone.

Read the root SKILL.md first. Then follow explicit links and references from SKILL.md, AGENTS.md, and other instruction files. After that, broaden to a recursive crawl of likely behavior-bearing support files in the skill folder. This includes linked files and other likely behavior-bearing files such as content under references/, templates, checklists, and instruction artifacts, even if the user did not paste them inline.

Do not assume the visible excerpt is the full contract.

If file discovery is inconclusive, treat that as unresolved rather than as evidence that no support files exist. Retry once with a simpler listing method or direct directory inspection. If you still cannot establish the file set, tell the user that the crawl is incomplete before you rewrite anything that could require cross-file alignment.

Done when: You can name the files that complete the behavior contract, or you have disclosed that the crawl is incomplete.

Serial-order detection and handling

Treat sequence as behavior when the text tells the agent or reader to do one thing before another.

Load references/serial-instruction-guidance.md before you edit workflow-bearing prose whose order, approval timing, validation loop, branch logic, or reference-loading sequence matters. Keep SKILL.md operational. Use the reference for the detailed detection pass, structure rules, and edge cases.

Serial-order step 1: Classify each workflow unit before you restructure it

Classify each unit as one of these:

• Action — do something now
• Gate — stop, wait, require, or branch
• Readiness check — confirm outputs exist or state is complete
• Stage note — purpose, context isolation, rationale, or input scope
• Branch handler — handle approve / request changes / manual edit
• Landmark checkpoint — a named pause or review moment that downstream prose may reference

Do not give all six categories the same structural weight. Done when: Every unit you may reshape has a category.

Serial-order step 2: Detect ordered behavior before you tighten it

Requires: Complete Serial-order step 1. Detect and make these cases explicit without adding new behavior:

• explicit serial instructions — numbered steps, Step 1, first/next/then/finally, before/after/until, requires, done when, return to, do not proceed until
• implied step ordering — one sentence hides multiple actions, one action uses the output of another, a warning implies an unstated gate, a qualitative cue acts as a hidden fallback condition, or a paragraph mixes discovery, decision, rewrite, and verification
• sequencing cues in skill files — choose output mode before rewrite mode, define the artifact set before cross-file edits, load references before citing them, run self-check before delivery, ask first before edits that need approval
• sequencing cues in general prose — procedural paragraphs, approval notes, policy instructions, workflow warnings, and bullets that are really ordered tasks Done when: You can name the ordered actions, gates, checks, and branches that the rewrite must preserve.

Serial-order step 3: Choose the smallest ordered structure that keeps compliance visible

Requires: Complete Serial-order step 2. When order matters:

• make the order explicit
• use a numbered list for 2 to 3 short ordered steps
• use ### Step 0 plus a checklist, then ### Step N: Name, for 4 or more ordered steps
• give every ### Step N: Name block an operational body, gate, or completion condition
• do not create a numbered step if it only restates stage purpose, repeats a nearby context rule, announces the next phase, or preserves numbering without operational value
• add Requires: when a step depends on an earlier step
• add Done when: when later work depends on a successful check
• add a named failure route when a later step must wait for a passing check
• split do X and then Y into separate steps when compliance would be safer
• put conditions before actions when that makes timing clearer
• restate an enforceable gate only when the source already makes the dependency mandatory through explicit timing, requirement, or stop/wait language
• never leave ordered work in plain bullets Done when: The workflow shape makes the intended order, gates, and retry path hard to miss.

Serial-order step 4: Preserve stage mechanics and reject filler steps

Requires: Complete Serial-order step 3. For stage-based workflows:

• if the document already names stages or phases in multiple places, treat that as evidence of an existing organizing mechanic
• prefer a ## Stage: container or equivalent higher-level heading when several consecutive items share one phase purpose
• keep phase purpose, context-isolation rules, rationale, and entry conditions at stage level unless they need a standalone numbered checkpoint
• preserve landmark step numbers when they are reused across the file or tied to checkpoints
• do not preserve low-value filler steps only to keep numbering contiguous
• if stage boundaries, numbering architecture, checkpoint placement, or overview/checklist alignment would change, classify the rewrite as structural and surface that explicitly

Transition-step rule:

• a transition step is acceptable only when it enforces a real prohibition, readiness boundary, or handoff state that later steps depend on
• a transition step is not acceptable if the surrounding stage container already makes the navigation obvious Done when: Stage notes stay at stage level, operational steps stay operational, and any structural rewrite is disclosed as structural.

Rewrite method

Use this method whenever you rewrite behavior-defining prose.

Rewrite-method step 1: Lead with the operational point

Start with the rule, action, boundary, or decision the reader must understand.

• In descriptions, surface the scope logic early.
• In workflow prose, surface the action and sequence early.
• In guardrails, surface the requirement or prohibition early.
• In rationale, surface the protected risk early.

Do not add a preamble when the instruction works better without one.

Rewrite-method step 2: Keep one term for one concept

Requires: Complete Rewrite-method step 1.

Pick one term for each repeated behavior-bearing concept and keep it stable.

Do not rotate synonyms for style if those synonyms could suggest different scope, timing, or force.

Rewrite-method step 3: Match the sentence shape to the job

Requires: Complete Rewrite-method steps 1 and 2.

Choose the clearest sentence shape that stays accurate for the artifact.

• Descriptions — keep the trigger family, boundary, and artifact scope explicit.
• Procedures — keep one action or decision per step when possible.
• Guardrails — keep the prohibition or requirement direct, then explain the risk if needed.
• Rationale — explain why the rule exists without burying the rule itself.
• Examples — keep only examples that anchor scope, edge cases, or expected behavior.

Rewrite-method step 4: Separate instruction from explanation when it helps

Requires: Complete Rewrite-method steps 1 to 3.

Procedural text tells the agent what to do. Descriptive text explains what something means, why a rule exists, or when a rule applies.

Separate them when that makes behavior easier to follow. Do not force everything into imperative form if that would narrow policy text, flatten rationale, or blur scope.

Rewrite-method step 5: Put conditions before commands when that clarifies the logic

Requires: Complete Rewrite-method steps 1 to 4.

If a rule depends on a condition, put the condition first when doing so makes the logic easier to follow and does not change timing or emphasis.

Rewrite-method step 6: Preserve exact obligation strength

Requires: Complete Rewrite-method steps 1 to 5.

Keep requirement, recommendation, permission, and prohibition at the same level.

Preserve original obligation wording by default. Use RFC 2119 terms only when the user explicitly asked for normalization or when the source already states the obligation level unambiguously and the conversion is strictly lossless. Do not normalize severity labels mechanically or just to sound more formal.

Rewrite-method step 7: Keep the action path easy to scan

Requires: Complete Rewrite-method steps 1 to 6.

Use short paragraphs, clean lists, and bounded sentences when they make the behavior easier to audit.

Do not reshape source text just to make it feel lighter. Scanability helps only when it preserves the same behavior.

Rewrite-method step 8: Use the smallest structure that makes the rule clear

Requires: Complete Rewrite-method steps 1 to 7.

Do not over-edit. Improve the prose enough to make the intended behavior easier to follow and harder to misread.

If the workflow already has an implicit stage model, prefer stage-aware cleanup over flattening adjacent notes into peer numbered steps.

Core rules

1. Treat descriptions as trigger logic

Frontmatter descriptions help decide when the skill is used.

When tightening a description:

• preserve the same kinds of requests
• preserve scope-defining nouns and verbs
• preserve quoted trigger phrases unless the user asked to change them
• do not add adjacent trigger families unless expansion was explicitly requested
• do not convert a short description into a broad trigger inventory unless the user asked for that

If a phrase does trigger work, keep it, or replace it only with wording that preserves the same scope exactly.

2. Treat workflow prose as executable guidance

If an agent followed only the rewritten text, the agent should behave the same way.

Separate procedural text from descriptive text when that distinction helps clarity. Procedural text tells the agent what to do. Descriptive text explains what something means, why a guardrail exists, or when a rule applies. Do not force descriptive or policy text into imperative form if that would change behavior or make the constraint sound narrower than it is.

Check for:

• step order
• before/after timing
• approval dependencies
• conditions that gate an action
• qualitative fallback or exception wording that can gate an action without an operational boundary
• warnings that explain why a step matters
• verbs that carry behavior, such as stop, pause, wait, proceed, skip, require, or allow
• stage boundaries or phase markers that already organize the workflow
• landmark checkpoints that other sections may reference

Do not merge steps or compress qualifiers if doing so hides decision points. Do not promote stage notes, rationale, or handoff summaries into standalone numbered steps unless they carry real operational weight.

If the document already names phases or stages in multiple places, consider a stage-aware rewrite rather than a flat step rewrite. If preserving important checkpoints conflicts with step quality, surface that tradeoff explicitly instead of padding the workflow with filler steps.

Do not swap a behavior-bearing verb for a near-synonym unless the new wording preserves the same permission, timing, and obligation level.

3. Preserve exact references exactly

Keep these exact unless the user explicitly asks otherwise:

• file names and paths
• commands and flags
• field names and keys
• identifiers
• slash-joined references
• rule labels
• quoted errors or logs
• inline code and code blocks

If the source names a specific token like specs_touched/decisions, keep that token exactly.

4. Preserve hard-stop strength

If the source contains words like must, do not, never, required, or severity labels such as critical and important, preserve the same obligation level.

When rewriting behavior-defining prose, preserve original obligation wording by default. Convert informal severity labels to RFC 2119 terms only when the user explicitly requested standardization or the source already pairs the label with unmistakable normative language, and the conversion is strictly lossless. Apply this cautiously to heading-level or banner-level labels like MANDATORY CHECKPOINT, CRITICAL STEP, or IMPORTANT too, not only sentence-level prose. Do not apply this mechanically to quoted text, exact tokens, or other untouchables that must stay exact. Do not normalize just for tone or formality. Never infer requirement level from rhetorical emphasis alone.

A clearer version must preserve the same obligation level.

Bad pattern:

• must → should
• do not → avoid
• required → recommended

5. Prefer minimal safe tightening

Cut a word only when that word does not anchor trigger scope, differentiate the skill from adjacent skills, preserve a workflow step, or carry exact technical meaning.

Use direct English. Cut filler, stale phrasing, and avoidable abstraction.

Remove only words that are not carrying behavior.

Good edits:

• split long sentences without changing sequence
• move conditions before commands when the meaning stays the same
• replace inflated wording with concrete wording
• standardize repeated terms
• keep required nouns, verbs, subjects, and articles explicit rather than omitting them for brevity
• prefer active voice unless passive wording is necessary to preserve meaning or actor ambiguity
• remove extra framing when it adds no operational meaning
• preserve the source format when format is part of the request, such as note, checklist, banner, heading, or short inline instruction
• for short practical notes, prefer the smallest local rewrite that improves scanability without escalating tone, adding process detail, or turning the note into a policy artifact

Bad edits:

• compressing away a trigger phrase
• replacing an exact field reference with a broader category
• deleting an example that anchors scope
• turning a bounded instruction into a generic best practice

6. Prefer no rewrite over risky rewrite

If the source is already clear enough and further tightening risks drift, say so.

Preserve trigger accuracy and workflow behavior over elegance. A clumsy instruction that works is better than a polished one that drifts.

A safe answer can be:

• a very small rewrite
• an audit with no rewrite
• a note that the wording is already near the minimum safe form

If the text is already compact, exact, and behaviorally clear, prefer an explicit no-rewrite recommendation over a cosmetic rephrase.

Output rules by mode

Rewrite mode controls how far you may reshape the source. Output mode controls what you return to the user.

For your own responses, you may use lightweight navigation aids when they improve scanability without changing claim strength. Good examples include numbered findings, explicit next steps, and brief progress-visible summaries.

Formatting help applies to the response only, not to the source text or its policy content. Do not let response-formatting choices override audit accuracy. Do not reshape source text just to make it feel more ADHD-friendly unless the user explicitly asked for that delivery style.

Audit only

Use this structure:

1. Summary — 1 to 3 sentences
2. Highest-risk issues first
3. Finding list — category, source text, risk, and why it matters
4. Optional safer alternative — only if the user explicitly asked for examples, and only at finding level
5. Optional full rewrite — only if the user asked for it
6. Completed report — fill out assets/output-template.md

Focus first on:

• trigger drift risk
• workflow drift risk
• guardrail weakening
• exact-reference loss
• only then general clarity issues

Use calibrated obligation and severity language, not theatrics. Prefer RFC 2119 terms when describing the strength of a rule or rewrite recommendation. Use severity labels only when they help rank audit findings rather than define behavior. Reserve labels like Critical for issues likely to change agent behavior, trigger routing, workflow execution, approval handling, or safety boundaries.

Rewrite only

Always include the consistent report from assets/output-template.md.

If the user asks for only the rewrite, return the rewrite first, then the completed report.

Do not prepend audit notes or explanation unless the user asked.

Audit plus rewrite

Always include the consistent report from assets/output-template.md.

Give the risk summary first. Then give the rewrite. Then give the completed report.

Progressive disclosure

Load references only when the task needs them.

When the user asks you to work on a skill, crawl the skill folder first. Treat the skill folder as one behavior contract distributed across an artifact set, not as a root file with optional extras.

For folder-level work, the default artifact set is the local SKILL.md, sibling AGENTS.md if present, and behavior-bearing Markdown under references/.

Do the crawl in order. Read the local SKILL.md first. Then follow explicit links and references from SKILL.md, AGENTS.md, and adjacent instruction files before you broaden to other likely behavior-bearing files such as references/ content, templates, checklists, or adjacent instruction files.

When the task covers a skill folder, audit the artifact set, not only the quoted excerpt. Rewrite other artifact-set files only when a source-preserving inconsistency would otherwise remain after the requested edit, such as a mismatch in terminology, obligation level, examples that define scope, workflow wording, or progressive-disclosure handoffs.

If you changed any file in the artifact set, run a consistency check across the other inspected behavior-bearing files before you conclude that they should stay unchanged. This check is separate from cross-file alignment. Rewrite another file only if the first change would otherwise create a concrete mismatch in trigger scope, workflow semantics, obligation level, exact references, or behavior-bearing terminology. Do not propagate optional stylistic preferences across files.

If you leave an inspected behavior-bearing file unchanged, classify the reason explicitly as one of these:

• Already near minimum safe form
• Rewrite would add drift risk without meaningful clarity gain
• Local-tightening sweep incomplete

Do not collapse these into a generic No edit needed.

Consider local sentence structure only after behavior-preservation checks pass and only for low-risk, local edits. A file can be behaviorally aligned across the folder and still justify a rewrite, but do not rewrite solely to improve prose quality if the file is already behaviorally clear.

Load references only when needed:

• references/serial-instruction-guidance.md — explicit and implied step order, approval timing, validation loops, branching, and when workflow prose must become stronger ordered steps
• references/checklist.md — final pass before delivery, output-mode compliance, no-rewrite decisions, and cross-file consistency checks
• references/frontmatter-descriptions.md — description tightening, trigger-family preservation, and trigger-scope safety