{"id":"942fc304-6e51-4e0e-b3ba-edbae1b40de9","shortId":"Bb8gnj","kind":"skill","title":"improve-skill","tagline":"Use when the user asks to improve, compare, audit, or identify gaps in an existing skill.","description":"skill_name = $ARGUMENTS\n\nIf no argument, ask.\n\n## Finding the Skill\n\nSearch in order: `~/.claude/skills/{skill_name}/SKILL.md` → `~/.claude/skills/{skill_name}/*.md` → `.rulesync/skills/{skill_name}/SKILL.md`. Read completely, including referenced files.\n\n## Philosophy\n\nThe goal is often making a skill *shorter*, not longer — cutting bloat is as valuable as adding techniques. Subtraction requires independent judgment formed *before* seeing what competitors do. Research without a prior assessment just produces parroting.\n\n## Self-Assessment\n\nForm hypotheses before external research. Assess two dimensions:\n\n### Capability Gaps & Contradictions\n\nWhat the skill likely should do but doesn't. Where it contradicts its own philosophy.\n\n### Agent-Execution Quality\n\nEvaluate the skill as a *prompt for an executing agent*, not a document for a human. This is the higher-value analysis — most skills have acceptable coverage but poor prompt engineering.\n\n| Check | What to look for |\n|-------|-----------------|\n| **Why-motivation** | Unmotivated directives (MUST/NEVER/ALWAYS without reasoning) get dropped by agents under pressure. Count them. |\n| **Adaptive scaling** | Does workflow adjust to task complexity? A 2-file task shouldn't trigger the same pipeline as a 50-file task. |\n| **Progressive disclosure** | Skills over ~300 lines of core workflow suffer attention dilution. Are details in reference files loaded on demand? |\n| **Failure mode awareness** | \"You'll be tempted to skip this because...\" outperforms \"MUST complete this step.\" Does the skill anticipate agent failure modes? |\n| **Escape hatches** | Can the agent skip phases that don't apply? |\n| **Constraint density** | Above ~5 unmotivated constraints per 100 lines = attention dilution risk. |\n| **Tone** | Explanatory (\"because X, do Y\") > directive (\"NEVER do X\"). Explanatory tone lets the agent reason about edge cases. |\n| **File references** | `!path/to/file.md` (inline injection) > plain paths (requires extra read). |\n| **Phantom constraints** | Instructions the model would follow anyway. If no competitor bothers instructing it, the model handles it without being told. |\n\nWrite down all hypotheses. Research will validate or invalidate them.\n\n## Competitive Research\n\nSpawn **three research teammates in parallel**. For each: read the prompt file from `${CLAUDE_SKILL_DIR}/agents/<name>.md`, pass its full content as the teammate's prompt, prepend the skill summary and your hypotheses for context.\n\n| Teammate | File | Purpose |\n|----------|------|---------|\n| System Prompts Analyzer | `agents/system-prompts.md` | Compare against other AI coding tools' system prompts |\n| Ecosystem Scanner | `agents/ecosystem.md` | Search open skills registry for similar skills |\n| Vendor Docs Researcher | `agents/vendor-docs.md` | Search vendor docs and best practices |\n\n## Synthesis & Report\n\nAfter all teammates complete, look for: which hypotheses research validated, insights that emerge from *combining* sources, and what to cut — apply the **phantom constraint test**: if no competitor instructs it and the model would do it anyway, flag for removal.\n\nPresent as a single consolidated report:\n\n**1. Executive summary** (2-3 sentences) — ahead, behind, or on par? Over-engineered, under-engineered, or right-sized?\n\n**2. Agent-execution quality assessment:**\n\n| Check | Current State | Recommendation | Priority |\n|-------|--------------|----------------|----------|\n\n**3. Gap analysis:**\n\n| Category | Have | Missing | Could Cut | Priority | Sources |\n|----------|------|---------|-----------|----------|---------|\n\n**4. Recommended removals** — concrete sections to delete, with rationale.\n\n**5. Recommended additions** — highest-impact first, with concrete text. Severity: CRITICAL (most competitors have it, significantly impacts quality) → HIGH → MEDIUM → LOW.\n\n**6. Net effect** — will the skill get longer, shorter, or stay the same? Aim for shorter-or-same.\n\n**7. Unique strengths** to preserve.\n\n**8. Anti-patterns** — techniques from competitors to explicitly NOT adopt, with reasoning.\n\n**STOP.** Wait for user approval before modifying anything.\n\n## Implementation (After Approval)\n\nApply removals before additions — models default to additive changes; subtract first to prevent the skill from growing. Convert plain file paths to `!path/to/file.md` inline injection where appropriate. Report net line count change — a negative number is a good sign.\n\nWhen rewriting, apply the `/prompt` skill's design principles.","tags":["improve","skill","dotclaude","jhostalek","agent-skills","ai-coding","anthropic","claude","claude-code","claude-code-skills","code-review","codex-cli"],"capabilities":["skill","source-jhostalek","skill-improve-skill","topic-agent-skills","topic-ai-coding","topic-anthropic","topic-claude","topic-claude-code","topic-claude-code-skills","topic-code-review","topic-codex-cli","topic-cursor","topic-developer-tools","topic-git-workflow","topic-multi-agent"],"categories":["dotclaude"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/JHostalek/dotclaude/improve-skill","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add JHostalek/dotclaude","source_repo":"https://github.com/JHostalek/dotclaude","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (4,509 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:16.134Z","embedding":null,"createdAt":"2026-05-18T13:20:32.868Z","updatedAt":"2026-05-18T19:13:16.134Z","lastSeenAt":"2026-05-18T19:13:16.134Z","tsv":"'-3':447 '/.claude/skills':33,37 '/agents':340 '/prompt':607 '/skill.md':36,44 '1':443 '100':257 '2':182,446,464 '3':475 '300':200 '4':485 '5':253,494 '50':193 '6':516 '7':535 '8':540 'accept':146 'ad':67 'adapt':173 'addit':496,567,571 'adjust':177 'adopt':550 'agent':117,129,168,236,243,276,466 'agent-execut':116,465 'agents/ecosystem.md':377 'agents/system-prompts.md':366 'agents/vendor-docs.md':388 'ahead':449 'ai':370 'aim':529 'analysi':142,477 'analyz':365 'anti':542 'anti-pattern':541 'anticip':235 'anyth':560 'anyway':298,433 'appli':249,417,564,605 'appropri':590 'approv':557,563 'argument':22,25 'ask':8,26 'assess':83,89,95,469 'attent':206,259 'audit':12 'awar':218 'behind':450 'best':393 'bloat':62 'bother':302 'capabl':98 'case':280 'categori':478 'chang':572,595 'check':152,470 'claud':337 'code':371 'combin':411 'compar':11,367 'competit':322 'competitor':77,301,424,507,546 'complet':46,229,400 'complex':180 'concret':488,502 'consolid':441 'constraint':250,255,292,420 'content':345 'context':359 'contradict':100,112 'convert':581 'core':203 'could':481 'count':171,594 'coverag':147 'critic':505 'current':471 'cut':61,416,482 'default':569 'delet':491 'demand':215 'densiti':251 'design':610 'detail':209 'dilut':207,260 'dimens':97 'dir':339 'direct':161,268 'disclosur':197 'doc':386,391 'document':132 'doesn':108 'drop':166 'ecosystem':375 'edg':279 'effect':518 'emerg':409 'engin':151,456,459 'escap':239 'evalu':120 'execut':118,128,444,467 'exist':18 'explanatori':263,272 'explicit':548 'extern':93 'extra':289 'failur':216,237 'file':49,183,194,212,281,335,361,583 'find':27 'first':500,574 'flag':434 'follow':297 'form':73,90 'full':344 'gap':15,99,476 'get':165,522 'goal':52 'good':601 'grow':580 'handl':307 'hatch':240 'high':513 'higher':140 'higher-valu':139 'highest':498 'highest-impact':497 'human':135 'hypothes':91,315,357,404 'identifi':14 'impact':499,511 'implement':561 'improv':2,10 'improve-skil':1 'includ':47 'independ':71 'inject':285,588 'inlin':284,587 'insight':407 'instruct':293,303,425 'invalid':320 'judgment':72 'let':274 'like':104 'line':201,258,593 'll':220 'load':213 'longer':60,523 'look':155,401 'low':515 'make':55 'md':40,341 'medium':514 'miss':480 'mode':217,238 'model':295,306,429,568 'modifi':559 'motiv':159 'must':228 'must/never/always':162 'name':21,35,39,43 'negat':597 'net':517,592 'never':269 'number':598 'often':54 'open':379 'order':32 'outperform':227 'over-engin':454 'par':453 'parallel':329 'parrot':86 'pass':342 'path':287,584 'path/to/file.md':283,586 'pattern':543 'per':256 'phantom':291,419 'phase':245 'philosophi':50,115 'pipelin':190 'plain':286,582 'poor':149 'practic':394 'prepend':351 'present':437 'preserv':539 'pressur':170 'prevent':576 'principl':611 'prior':82 'prioriti':474,483 'produc':85 'progress':196 'prompt':125,150,334,350,364,374 'purpos':362 'qualiti':119,468,512 'rational':493 'read':45,290,332 'reason':164,277,552 'recommend':473,486,495 'refer':211,282 'referenc':48 'registri':381 'remov':436,487,565 'report':396,442,591 'requir':70,288 'research':79,94,316,323,326,387,405 'rewrit':604 'right':462 'right-siz':461 'risk':261 'rulesync/skills':41 'scale':174 'scanner':376 'search':30,378,389 'section':489 'see':75 'self':88 'self-assess':87 'sentenc':448 'sever':504 'shorter':58,524,532 'shorter-or-sam':531 'shouldn':185 'sign':602 'signific':510 'similar':383 'singl':440 'size':463 'skill':3,19,20,29,34,38,42,57,103,122,144,198,234,338,353,380,384,521,578,608 'skill-improve-skill' 'skip':224,244 'sourc':412,484 'source-jhostalek' 'spawn':324 'state':472 'stay':526 'step':231 'stop':553 'strength':537 'subtract':69,573 'suffer':205 'summari':354,445 'synthesi':395 'system':363,373 'task':179,184,195 'teammat':327,348,360,399 'techniqu':68,544 'tempt':222 'test':421 'text':503 'three':325 'told':311 'tone':262,273 'tool':372 'topic-agent-skills' 'topic-ai-coding' 'topic-anthropic' 'topic-claude' 'topic-claude-code' 'topic-claude-code-skills' 'topic-code-review' 'topic-codex-cli' 'topic-cursor' 'topic-developer-tools' 'topic-git-workflow' 'topic-multi-agent' 'trigger':187 'two':96 'under-engin':457 'uniqu':536 'unmotiv':160,254 'use':4 'user':7,556 'valid':318,406 'valu':141 'valuabl':65 'vendor':385,390 'wait':554 'why-motiv':157 'without':80,163,309 'workflow':176,204 'would':296,430 'write':312 'x':265,271 'y':267","prices":[{"id":"b50ef853-6463-44c5-b086-f6523ab6cb31","listingId":"942fc304-6e51-4e0e-b3ba-edbae1b40de9","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"JHostalek","category":"dotclaude","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:32.868Z"}],"sources":[{"listingId":"942fc304-6e51-4e0e-b3ba-edbae1b40de9","source":"github","sourceId":"JHostalek/dotclaude/improve-skill","sourceUrl":"https://github.com/JHostalek/dotclaude/tree/main/skills/improve-skill","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:32.868Z","lastSeenAt":"2026-05-18T19:13:16.134Z"}],"details":{"listingId":"942fc304-6e51-4e0e-b3ba-edbae1b40de9","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"JHostalek","slug":"improve-skill","github":{"repo":"JHostalek/dotclaude","stars":8,"topics":["agent-skills","ai-coding","anthropic","claude","claude-code","claude-code-skills","code-review","codex-cli","cursor","developer-tools","git-workflow","multi-agent","prompt-engineering","skill-md"],"license":"cc0-1.0","html_url":"https://github.com/JHostalek/dotclaude","pushed_at":"2026-05-17T15:07:41Z","description":"Agent skills for agentic coding tools. Extremely opinionated. Updated (almost) daily.","skill_md_sha":"43649ae1ae11adc5ea8ea872861b94ed5c577084","skill_md_path":"skills/improve-skill/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/JHostalek/dotclaude/tree/main/skills/improve-skill"},"layout":"multi","source":"github","category":"dotclaude","frontmatter":{"name":"improve-skill","description":"Use when the user asks to improve, compare, audit, or identify gaps in an existing skill."},"skills_sh_url":"https://skills.sh/JHostalek/dotclaude/improve-skill"},"updatedAt":"2026-05-18T19:13:16.134Z"}}