Shortify

Skill kolodkin/devpowers/skills/shortify

Review and shorten markdown docs, code comments, and docstrings — cut wordiness, redundancy, and code duplication. TRIGGER on .md file edits inside subdirectories, or when user asks to shorten/condense docs, comments, or docstrings. Skip root-level .md files (CLAUDE.md, README.md, CHANGELOG.md, etc.).From its SKILL.md

Install

npx -y skills add kolodkin/devpowers --skill shortify

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.5 KB, as published. Nobody here has run it

shortify

Apply as a review pass after writing or editing .md files in subdirectories, or manually via /shortify [file-or-glob].

Scope: Any .md file inside a subdirectory (e.g. docs/, src/), plus code comments and docstrings in source files. Skip: CLAUDE.md, README.md, CHANGELOG.md, LICENSE.md, and any root-level .md files — these have their own conventions.

Auto vs. manual:

Markdown triggers automatically as a review pass after .md edits in subdirectories.
Code comments & docstrings are manual-only — never auto-triggered by a code edit. Run them on request: /shortify <file-or-glob> on source files, or when the user opts in for the session ("apply shortify to my comments this session"), after which apply it as a review pass to code you edit for the rest of that session.

Checklist (markdown)

Apply in order:

1. Kill Redundancy

Remove text that restates what code already shows — link to the source instead.
One example per concept. Delete duplicates.
Merge overlapping sections — keep the clearer one.

2. Cut Wordiness

Replace wordy phrases: "In order to" -> "To", "It is important to note that" -> delete, "This allows you to" -> delete or rephrase.
Remove filler sentences that add no information.
Prefer bullet lists over paragraphs for reference material.

3. Tighten Structure

Delete empty/trivial sections. Merge one-sentence sections into neighbors.
Shorten introductions — title + one sentence is enough.
Flatten heading depth: # and ## only. Avoid ### and deeper — restructure instead.

4. Reference Code, Don't Duplicate

Replace inline implementations with references: See DataContext.query() in aaiclick/data/data_context.py.
Keep short usage examples (3-5 lines). Delete long inline code.
API docs: call signature + one example, not internals.

5. Preserve

Content with no other source (design decisions, rationale, gotchas).
Non-obvious usage examples and genuine !!! warning admonitions.
Do NOT change referenced code — only the surrounding text.

Checklist (code comments & docstrings)

Cut redundancy, keep intent. Change comment/docstring text only — never logic.

1. Delete the "what", keep the "why"

Remove comments that restate the code: i += 1 # increment i, # constructor, # return result.
Keep comments that explain why — intent, rationale, non-obvious decisions, gotchas, genuine warnings.
Collapse a multi-line comment that says one thing into one line.

2. Tighten docstrings

Keep the contract: one-line summary + params/returns/raises per the project's convention.
Don't repeat type info already in the signature or annotations.
At most one example, and only when it adds something the signature doesn't.
Apply the same wordiness cuts as markdown (see "Cut Wordiness" above).

3. Preserve

Tooling directives: # noqa, # type: ignore, eslint-disable, # pragma, shebangs, encoding lines.
License/copyright headers, TODO/FIXME, doctest examples, and public-API docs required by convention.
Anything load-bearing for behavior or tooling — when unsure, leave it.

Output

Show before/after line count and a brief summary of cuts. Commit if approved.