New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Official agent skill

Readability Feedback

by JetBrains in JetBrains/youtrackdb

Audit a finished design document for hard-to-read or hard-to-understand paragraphs, then harden the house-style rules so future design docs avoid them.

OfficialApache-2.0Auto-check passedWriting & Content

Install Readability Feedback

skills CLI
$ npx skills add JetBrains/youtrackdb --skill readability-feedback -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install JetBrains/youtrackdb readability-feedback --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/JetBrains/youtrackdb.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/readability-feedback .claude/skills/readability-feedback && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
readability-feedback
GitHub stars
437
Token cost
~2.3k tokens
SKILL.md length
936 words
Files
1
Skills in repo
16
Repo updated
First seen
Licence
Apache-2.0

At a glance

Audit a finished design document for hard-to-read or hard-to-understand paragraphs, then harden the house-style rules so future design docs avoid them.

  • Works in 3 steps: A file path to design.md,… → An adr dir name — audit… → Empty — discover the current branch's…
  • The user wants to feed a design doc back into the style guide
  • SKILL.md covers When to use this, and when not, Inputs, Procedure and Rule sync map, plus 2 more sections
  • Calls python3

What it does

Readability Feedback is an agent skill from JetBrains/youtrackdb, published by the product's own GitHub organization. Audit a finished design document for hard-to-read or hard-to-understand paragraphs, then harden the house-style rules so future design docs avoid them. Fans out audit sub-agents, classifies each obscure passage as caught-by-an-existing-rule or a gap, and proposes plus (on approval) applies rule changes across the style docs. Use when the user wants to feed a design doc back into the style guide, find obscure paragraphs and fix the rules, harden the writing rules from a real DD, or close the readability feedback…

Its SKILL.md is about 2.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Writing & Content, covering Architecture decision records, Plain language and style rules and Subagents. The repository describes itself as: YouTrackDB is a general-use object-oriented graph database with storage format native to handle graph relations. YouTrackDB supports Gremlin queries and ACID transactions. YTDB… The licence is Apache-2.0.

When your agent uses it

  • The user wants to feed a design doc back into the style guide
  • Find obscure paragraphs and fix the rules
  • Harden the writing rules from a real DD
  • Close the readability feedback loop

Example prompts

  • “s design. Reports the doc”
  • “/readability-feedback”

Requirements

  • Python 3

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. A file path to design.md, design-final.md, or design-mechanics.md — audit that file (and its companion if both exist).
  2. An adr dir name — audit docs/adr//_workflow/design.md plus design-mechanics.md, or docs/adr//design-final.md if the working copy is gone.
  3. Empty — discover the current branch's design under docs/adr/. If more than one candidate exists, ask which.

What it can do on your machine

Read from SKILL.md and the folder at commit 82af9d5. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Readability Feedback loads about 2.3k tokens when it runs. Until then it costs about 173 tokens; SKILL.md has 936 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~173
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from JetBrains/youtrackdb at commit 82af9d5, republished under its Apache-2.0 licence (© JetBrains). 936 words, ~2,345 tokens.

Download SKILL.mdSave it as .claude/skills/readability-feedback/SKILL.md (or your agent's skills folder).
name
readability-feedback
description
Audit a finished design document for hard-to-read or hard-to-understand paragraphs, then harden the house-style rules so future design docs avoid them. Fans out audit sub-agents, classifies each obscure passage as caught-by-an-existing-rule or a gap, and proposes plus (on approval) applies rule changes across the style docs. Use when the user wants to feed a design doc back into the style guide, find obscure paragraphs and fix the rules, harden the writing rules from a real DD, or close the readability feedback loop. Accepts a design-doc path, an adr dir name, or defaults to the current branch's design. Reports the doc's own violations; does not rewrite the doc.
argument-hint
[design-doc-path | adr-dir | (default: current branch's design)]
user-invocable
true

Audit a design document for obscure prose and harden the house-style rules so the next design doc avoids the same trouble. The output is rule changes, not a rewrite of the audited doc.

This is the codified form of the manual loop: read a real DD, find the paragraphs a reviewer has to re-read, check whether a rule already forbids each one, and for the ones no rule catches, add or sharpen a rule in the style docs.

When to use this, and when not

Use it when the user points at a finished or near-finished design document and wants the rules improved from it: "harden the style from this design", "find the hard-to-read paragraphs and fix the rules", "feed this DD back into the style guide".

Distinct from three neighbors: ai-tells rewrites a draft; review-docs validates a doc's grammar and query correctness; self-improvement-reflection files YouTrack friction issues. This one edits the prose rules in house-style.md and its sync set, driven by a real DD.

It does not rewrite the audited design document. Design docs are frozen after Phase 1 or live on another branch, so the skill reports their obscure paragraphs for the author to fix separately and changes only the rule docs.

Inputs

$ARGUMENTS resolves in this order:

  1. A file path to design.md, design-final.md, or design-mechanics.md — audit that file (and its companion if both exist).
  2. An adr dir name — audit docs/adr/<dir>/_workflow/design.md plus design-mechanics.md, or docs/adr/<dir>/design-final.md if the working copy is gone.
  3. Empty — discover the current branch's design under docs/adr/. If more than one candidate exists, ask which.

The authoritative ruleset is always the live .claude/output-styles/house-style.md in the repo, never a copy.

Procedure

  1. Resolve the target. Confirm the file(s) exist. Capture section boundaries with grep -nE '^#{1,3} ' <file> and the line count.
  2. Partition. Split the doc into ~200-line ranges on ## / # Part boundaries; give each companion file (design-mechanics.md) its own range. Cap at ~6 sub-agents. This is the same partition value (window size, boundary set, cap) that the in-loop readability-auditor fan-out reuses; edit-design/SKILL.md § Step 4 is the canonical home of that value, and this tool applies it locally — keep the two in sync so the standalone tool and the in-loop path cannot drift. Only the partition value is shared: this tool fans out general-purpose sub-agents with the self-contained inline prompt below (step 3), so it does not adopt the in-loop path's whole-doc floor, its agent-side whole-doc guard, or its slice_count / total_lines params (those sub-agents take no params file).
  3. Fan out the audit. Launch one general-purpose sub-agent per range, in parallel, with the dispatch prompt in ## Audit sub-agent prompt below (fill {TARGET_PATH}, {START}, {END}). Each agent reads house-style.md in full, audits only its range, and classifies every obscure passage as CAUGHT by § <section> or GAP.
  4. Synthesize. Merge the findings. Split them into CAUGHT (the doc's own violations) and GAP (no rule catches). Group the GAPs by underlying tell, and fold an aggravated-but-caught residual into the nearest group.
  5. Draft one rule change per GAP group. Name the rule, the target section (general tells go under Banned sentence patterns / Banned analysis patterns / Structural rules; design-doc-shape tells go under Document-shape rules), the scope, a Before/After grounded in the real finding, and the sync set it triggers (see ## Rule sync map).
  6. Gate. Present two things and stop for approval: (a) the obscure-paragraph report with file:line for both CAUGHT and GAP, and (b) the proposed rule changes grouped by tell. Apply only what the user approves. Editing the rules is never automatic, because every rule applies to every future design doc.
  7. Apply through the sync discipline. For each approved rule, walk ## Rule sync map and edit every file the rule's scope touches in one pass.
  8. Validate and report. Run the checks in ## Validation, report what changed, and offer to commit. Re-runs converge: because step 3 reads the current rules, a paragraph that was a GAP last time is CAUGHT next time.
Show full SKILL.md (280 more words)Show less

Rule sync map

When a rule is added or renamed, update every file its scope touches:

  • .claude/output-styles/house-style.md — the rule prose and the matching ## Self-check item (1-10). Always.
  • .claude/output-styles/house-conversation.md — the matching AI-tell enumeration line, only if the rule is general (it then applies to chat too). Skip for design-only rules.
  • .claude/workflow/prompts/design-review.md — a ### Human-reader cold-read additions bullet, the § Tone and depth count, and the TOC-row summary, only if the rule is a design-doc-shape rule the cold-read reviewer must verify. A rule on prose density or terseness (the kind ## Orientation and the over-dense AI-tells cover) instead joins the ### Prose AI-tell additions block, which scans both target=design and target=tracks and carries its own § Tone and depth evidence clause.
  • .claude/workflow/design-document-rules.md — the ## Mechanical checks table and/or the design-sync Human-reader enumeration, only if the rule is design-doc-scoped.
  • .claude/scripts/design-mechanical-checks.py — a regex constant wired into check_dsc_ai_tell, only if the pattern is cleanly regex-detectable. Most readability tells are judgment-only; say so and skip the script.

On a rename, run the governance grep from conventions.md §1.5 to find every pointer and update them in the same commit:

bash
grep -rnE '## Orientation|## Plain language|§ Orientation|§ Plain language|Banned sentence patterns|Banned analysis patterns' .claude/ CLAUDE.md

Orientation and Plain language are common words, so the scan matches them only in their ## or § heading-pointer form to stay precise; the other two names are distinctive enough to match bare.

Validation

  • python3 .claude/scripts/workflow-reindex.py --check — run after editing any .claude/workflow/** file; confirms the TOC regions still resolve.
  • Code-fence balance — after adding a Before/After block, confirm each fenced block has a matching closer. A raw fence count can mislead, because an inline code span may itself contain backtick delimiters.
  • After a rename, grep that no stale rule name survives anywhere under .claude/.

Audit sub-agent prompt

Dispatch this to each range agent, substituting the three placeholders:

text
Audit a YouTrackDB design document for hard-to-read prose and classify each finding against the house-style ruleset.

STEP 1 — Read the authoritative ruleset IN FULL: `.claude/output-styles/house-style.md`. Note especially § Orientation, § Plain language, § Banned sentence patterns, § Banned analysis patterns (and its subsections), § Punctuation and typography, § Structural rules (and its subsections), and § Document-shape rules.

STEP 2 — Read `{TARGET_PATH}`, lines {START}-{END} only.

STEP 3 — Find every obscure passage in that range: run-on multi-clause sentences; dense identifier soup with no connective tissue; nominalizations and placeholder words (nouns or pro-verbs); file:line, signature, or code-literal asides wedged into a sentence; inline (1)(2)(3) enumerations; broken or telegraphic grammar (a signature or runtime expression in the subject slot, a missing copula, a dropped relative pronoun, a split predicate); disconnected one-line assertions with no motivation. Audit prose and bullets only — skip Mermaid bodies, D/S codes, References footers, and headings.

STEP 4 — Classify each finding as `CAUGHT by § <exact section>` or `GAP`. A too-terse passage — prose that cannot be followed without opening the code, or a one-line assertion dropped with no motivation — is `CAUGHT by § Orientation`, not a GAP. A passage that is hard to read for uncommon words, long sentences, or idioms is `CAUGHT by § Plain language`, not a GAP. Mark GAP only after checking every relevant section; for a GAP, name in one sentence the dimension of unreadability no current rule addresses.

Do NOT propose rewrites. Return EXACTLY this Markdown, no preamble:

## Summary
- Range audited: {TARGET_PATH}:{START}-{END}
- Total findings: <n>
- Caught: <n>   GAP: <n>

## Findings
### F1
- Location: <file>:<line(s)>
- Phrase: "<verbatim quote>"
- Why obscure: <one sentence>
- Verdict: CAUGHT by § <section> | GAP
- If GAP — uncovered dimension: <one sentence>

© JetBrains, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/readability-feedback of JetBrains/youtrackdb.

Open the folder on GitHubat commit 82af9d5

Compare with similar skills

Readability Feedback next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Readability Feedback compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Readability Feedback this skillJetBrains/youtrackdb437—~2.3kAutomated safety check: PassApache-2.0
Kkirikkirifivetaku/gptaku-plugins-codex128—~12kAutomated safety check: PassMIT
Agent Stylepchalasani/claude-code-tools2k—~1.4kAutomated safety check: PassMIT
Parallel Code Reviewspencerpauly/awesome-cursor-skills841—~781Automated safety check: PassCC0-1.0
Technical Writing Standardcursor/plugins10k10 repos~2.4kAutomated safety check: PassNone
Docs Reader Reviewprisma/web1.1k—~2.4kAutomated safety check: PassNone

Similar skills

  • Kkirikkiri

    fivetaku/gptaku-plugins-codex

    Assemble and run a Codex-native agent team from one plain-language request.

    128 GitHub stars~12k tokensUpdated 29 days ago
    Writing & ContentAuto-check passed

  • Agent Style

    pchalasani/claude-code-tools

    Literature-backed English technical-prose writing rules (agent-style, 21 rules).

    2k GitHub stars~1.4k tokensUpdated 2 days ago
    DevelopmentAuto-check passed

  • Parallel Code Review

    spencerpauly/awesome-cursor-skills

    Run four parallel read-only subagents that each review the same diff from a different lens — security, performance, correctness, and readability — then merge findings into one report.

    841 GitHub stars~781 tokensUpdated 2 mo ago
    DevelopmentAuto-check passed

  • Technical Writing Standard

    cursor/plugins

    Official

    Applies four layers of technical-writing rules to docs, RFCs, readmes, PR descriptions and commit messages so a tired engineer follows them on the first read.

    10k GitHub starsUsed in 10 repos~2.4k tokens
    Writing & ContentAuto-check passed

  • Docs Reader Review

    prisma/web

    Official

    A skill your agent uses when a docs page or section has been written or rewritten and is about to be handed over, when the operator says "reader review", "does this read like a human wrote it", "too…

    1.1k GitHub stars~2.4k tokensUpdated today
    Writing & ContentAuto-check passed

  • Chinese Technical Writing

    leter/zh-tech-writing

    Sets writing rules for Chinese technical docs: short plain sentences, consistent typography and a checklist for removing AI-sounding filler.

    332 GitHub stars~656 tokensUpdated 13 days ago
    Writing & ContentAuto-check passed

More from JetBrains/youtrackdb

All 16 skills in this repo

  • Review Docs

    JetBrains/youtrackdb

    Official

    Review documentation files for grammar, factual accuracy, and query correctness.

    437 GitHub stars~3k tokensUpdated today
    Auto-check passed

  • Edit Design

    JetBrains/youtrackdb

    Official

    Apply an edit to design.md or design-mechanics.md through the mutation discipline: apply → auto-review → iterate → present.

    437 GitHub stars~21k tokensUpdated today
    Auto-check passed

  • Migrate Workflow

    JetBrains/youtrackdb

    Official

    Migrate a branch's docs/adr/<dir/workflow/ artifacts by replaying workflow-format commits from the per-artifact stamp base through HEAD.

    437 GitHub stars~12k tokensUpdated today
    Auto-check passed

  • Run Jmh Benchmarks Hetzner

    JetBrains/youtrackdb

    Official

    Provision a Hetzner CCX33 server, deploy the project, run JMH benchmarks, collect results, and destroy the server.

    437 GitHub stars~3.7k tokensUpdated today
    Auto-check: warnings

  • Review Workflow PR

    JetBrains/youtrackdb

    Official

    Review a workflow-style PR's design, plan, and track files in research-mode Q&A; auto-records observations and submits a line-anchored review via gh api.

    437 GitHub stars~11k tokensUpdated today
    Auto-check passed

  • AI Tells

    JetBrains/youtrackdb

    Official

    Reviews any draft for AI writing tells and produces a clean rewrite.

    437 GitHub stars~1.1k tokensUpdated today
    Auto-check passed

Categories

Questions about Readability Feedback

What does Readability Feedback do?

Audit a finished design document for hard-to-read or hard-to-understand paragraphs, then harden the house-style rules so future design docs avoid them. Readability Feedback is an agent skill from JetBrains/youtrackdb, published by the product's own GitHub organization. Audit a finished design document for hard-to-read or hard-to-understand paragraphs, then harden the house-style rules so future design docs avoid them.

When should I use Readability Feedback?

Readability Feedback fits situations like: the user wants to feed a design doc back into the style guide; find obscure paragraphs and fix the rules; harden the writing rules from a real DD; close the readability feedback loop.

How do I install Readability Feedback in Claude Code?

Run `npx skills add JetBrains/youtrackdb --skill readability-feedback -a claude-code`. Or copy the skill folder (.claude/skills/readability-feedback in JetBrains/youtrackdb) into .claude/skills/readability-feedback in your project. Claude Code loads it when a task matches its description.

How do I install Readability Feedback in Codex?

Run `npx skills add JetBrains/youtrackdb --skill readability-feedback -a codex`. Or copy the skill folder (.claude/skills/readability-feedback in JetBrains/youtrackdb) into .agents/skills/readability-feedback in your project. Codex loads it when a task matches its description.

Can I use Readability Feedback in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add JetBrains/youtrackdb --skill readability-feedback -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/readability-feedback, .gemini/skills/readability-feedback, .github/skills/readability-feedback and .opencode/skills/readability-feedback in your project.

What does Readability Feedback need to run?

Going by SKILL.md and its folder, Readability Feedback needs the command-line tools its instructions call (python3). Our summary lists: Python 3.

Does Readability Feedback access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Readability Feedback safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Readability Feedback use?

Readability Feedback is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Readability Feedback use?

About 2.3k tokens (SKILL.md is roughly 9.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Readability Feedback?

Skills that share tags, products or a category with Readability Feedback: Kkirikkiri (fivetaku/gptaku-plugins-codex, 128 stars), Agent Style (pchalasani/claude-code-tools, 2k stars), Parallel Code Review (spencerpauly/awesome-cursor-skills, 841 stars) and Technical Writing Standard (cursor/plugins, 10k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Readability Feedback?

JetBrains (a GitHub organization, an official publisher) maintains it in JetBrains/youtrackdb, which has 437 GitHub stars. The repository holds 16 skills in this directory. The repository was last updated on October 7, 2026.

Source: JetBrains/youtrackdb on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.