{"id":"ea4e55b5-a803-480c-8fb6-cbdbd47fc2f1","shortId":"hJJPce","kind":"skill","title":"ruff-recursive-fix","tagline":"Run Ruff checks with optional scope and rule overrides, apply safe and unsafe autofixes iteratively, review each change, and resolve remaining findings with targeted edits or user decisions.","description":"# Ruff Recursive Fix\n\n## Overview\n\nUse this skill to enforce code quality with Ruff in a controlled, iterative workflow.\nIt supports:\n\n- Optional scope limitation to a specific folder.\n- Default project settings from `pyproject.toml`.\n- Flexible Ruff invocation (`uv`, direct `ruff`, `python -m ruff`, or equivalent).\n- Optional per-run rule overrides (`--select`, `--ignore`, `--extend-select`, `--extend-ignore`).\n- Automatic safe then unsafe autofixes.\n- Diff review after each fix pass.\n- Recursive repetition until findings are resolved or require a decision.\n- Judicious use of inline `# noqa` only when suppression is justified.\n\n## Inputs\n\nCollect these inputs before running:\n\n- `target_path` (optional): folder or file to check. Empty means whole repository.\n- `ruff_runner` (optional): explicit Ruff command prefix (for example `uv run`, `ruff`, `python -m ruff`, `pipx run ruff`).\n- `rules_select` (optional): comma-separated rule codes to enforce.\n- `rules_ignore` (optional): comma-separated rule codes to ignore.\n- `extend_select` (optional): extra rules to add without replacing configured defaults.\n- `extend_ignore` (optional): extra ignored rules without replacing configured defaults.\n- `allow_unsafe_fixes` (default: true): whether to run Ruff unsafe fixes.\n- `ask_on_ambiguity` (default: true): always ask the user when multiple valid choices exist.\n\n## Command Construction\n\nBuild Ruff commands from inputs.\n\n### 0. Resolve Ruff Runner\n\nDetermine a reusable `ruff_cmd` prefix before building commands.\n\nResolution order:\n\n1. If `ruff_runner` is provided, use it as-is.\n2. Else if `uv` is available and Ruff is managed through `uv`, use `uv run ruff`.\n3. Else if `ruff` is available on `PATH`, use `ruff`.\n4. Else if Python is available and Ruff is installed in that environment, use `python -m ruff`.\n5. Else use any project-specific equivalent that invokes installed Ruff (for example `pipx run ruff`), or stop and ask the user.\n\nUse the same resolved `ruff_cmd` for all `check` and `format` commands in the workflow.\n\nBase command:\n\n```bash\n<ruff_cmd> check\n```\n\nFormatter command:\n\n```bash\n<ruff_cmd> format\n```\n\nWith optional target:\n\n```bash\n<ruff_cmd> format <target_path>\n```\n\nAdd optional target:\n\n```bash\n<ruff_cmd> check <target_path>\n```\n\nAdd optional overrides as needed:\n\n```bash\n--select <codes>\n--ignore <codes>\n--extend-select <codes>\n--extend-ignore <codes>\n```\n\nExamples:\n\n```bash\n# Full project with defaults from pyproject.toml\nruff check\n\n# One folder with defaults\npython -m ruff check src/models\n\n# Override to skip docs and TODO-like rules for this run\nuv run ruff check src --extend-ignore D,TD\n\n# Check only selected rules in a folder\nruff check src/data --select F,E9,I\n```\n\n## Workflow\n\n### 1. Baseline Analysis\n\n1. Run `<ruff_cmd> check` with the selected scope and options.\n2. Classify findings by type:\n\t- Autofixable safe.\n\t- Autofixable unsafe.\n\t- Not autofixable.\n3. If no findings remain, stop.\n\n### 2. Safe Autofix Pass\n\n1. Run Ruff with `--fix` using the same scope/options.\n2. Review resulting diff carefully for semantic correctness and style consistency.\n3. Run `<ruff_cmd> format` on the same scope.\n4. Re-run `<ruff_cmd> check` to refresh remaining findings.\n\n### 3. Unsafe Autofix Pass\n\nRun only if findings remain and `allow_unsafe_fixes=true`.\n\n1. Run Ruff with `--fix --unsafe-fixes` using the same scope/options.\n2. Review resulting diff carefully, prioritizing behavior-sensitive edits.\n3. Run `<ruff_cmd> format` on the same scope.\n4. Re-run `<ruff_cmd> check`.\n\n### 4. Manual Remediation Pass\n\nFor remaining findings:\n\n1. Fix directly in code when there is a clear, safe correction.\n2. Keep edits minimal and local.\n3. Run `<ruff_cmd> format` on the same scope.\n4. Re-run `<ruff_cmd> check`.\n\n### 5. Ambiguity Policy\n\nIf there are multiple valid solutions at any step, always ask the user before proceeding.\nDo not choose silently between equivalent options.\n\n### 6. Suppression Decision (`# noqa`)\n\nUse suppression only when all conditions are true:\n\n- The rule conflicts with required behavior, public API, framework conventions, or readability goals.\n- Refactoring would be disproportionate to the value of the rule.\n- The suppression is narrow and specific (single line, explicit code when possible).\n\nGuidelines:\n\n- Prefer `# noqa: <RULE>` over broad `# noqa`.\n- Add a brief reason comment for non-obvious suppressions.\n- If two or more valid outcomes exist, always ask the user which option to prefer.\n\n### 7. Recursive Loop and Stop Criteria\n\nRepeat steps 2 to 6 until one of these outcomes:\n\n- `<ruff_cmd> check` returns clean.\n- Remaining findings require architectural/product decisions.\n- Remaining findings are intentionally suppressed with documented rationale.\n- Repeated loop makes no progress.\n\nEach loop iteration must include `<ruff_cmd> format` before the next `<ruff_cmd> check`.\n\nWhen no progress is detected:\n\n1. Summarize blocked rules and affected files.\n2. Present valid options and trade-offs.\n3. Ask the user to choose.\n\n## Quality Gates\n\nBefore declaring completion:\n\n- Ruff returns no unexpected findings for the chosen scope/options.\n- All autofix diffs are reviewed for correctness.\n- No suppression is added without explicit justification.\n- Any unsafe fix with possible behavioral impact is highlighted to the user.\n- Ruff formatting is executed in every iteration.\n\n## Output Contract\n\nAt the end of execution, report:\n\n- Scope and Ruff options used.\n- Number of iterations performed.\n- Summary of fixed findings.\n- List of manual fixes.\n- List of suppressions with rationale.\n- Remaining findings, if any, and required user decisions.\n\n## Suggested Prompt Starters\n\n- \"Run ruff-recursive-fix on the whole repo with default config.\"\n- \"Run ruff-recursive-fix only on src/models, ignore DOC rules.\"\n- \"Run ruff-recursive-fix on tests with select F,E9,I and no unsafe fixes.\"\n- \"Run ruff-recursive-fix on src/data and ask me before adding any noqa.\"","tags":["ruff","recursive","fix","awesome","copilot","github","agent-skills","agents","custom-agents","github-copilot","hacktoberfest","prompt-engineering"],"capabilities":["skill","source-github","skill-ruff-recursive-fix","topic-agent-skills","topic-agents","topic-awesome","topic-custom-agents","topic-github-copilot","topic-hacktoberfest","topic-prompt-engineering"],"categories":["awesome-copilot"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/github/awesome-copilot/ruff-recursive-fix","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add github/awesome-copilot","source_repo":"https://github.com/github/awesome-copilot","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 33270 github stars · SKILL.md body (5,954 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-18T18:52:24.548Z","embedding":null,"createdAt":"2026-04-18T20:33:58.263Z","updatedAt":"2026-05-18T18:52:24.548Z","lastSeenAt":"2026-05-18T18:52:24.548Z","tsv":"'0':230 '1':245,425,428,458,508,549,734 '2':256,437,454,467,520,561,690,741 '3':272,448,478,494,530,567,749 '4':282,485,537,542,574 '5':299,579 '6':604,692 '7':682 'ad':779,893 'add':183,350,355,657 'affect':739 'allow':198,504 'alway':214,591,674 'ambigu':211,580 'analysi':427 'api':623 'appli':14 'architectural/product':704 'as-i':253 'ask':209,215,319,592,675,750,890 'autofix':18,94,442,444,447,456,496,770 'automat':90 'avail':261,277,287 'base':337 'baselin':426 'bash':339,343,348,353,360,370 'behavior':527,621,788 'behavior-sensit':526 'block':736 'brief':659 'broad':655 'build':225,241 'care':471,524 'chang':22 'check':7,134,330,340,354,378,386,403,410,418,430,489,541,578,698,728 'choic':221 'choos':599,754 'chosen':767 'classifi':438 'clean':700 'clear':558 'cmd':238,327 'code':42,164,174,553,648 'collect':122 'comma':161,171 'comma-separ':160,170 'command':144,223,227,242,333,338,342 'comment':661 'complet':759 'condit':613 'config':854 'configur':186,196 'conflict':618 'consist':477 'construct':224 'contract':803 'control':48 'convent':625 'correct':474,560,775 'criteria':687 'd':408 'decis':32,110,606,705,839 'declar':758 'default':60,187,197,201,212,374,382,853 'detect':733 'determin':234 'diff':95,470,523,771 'direct':69,551 'disproportion':632 'doc':391,864 'document':712 'e9':422,876 'edit':29,529,563 'els':257,273,283,300 'empti':135 'end':806 'enforc':41,166 'environ':294 'equival':75,306,602 'everi':800 'exampl':147,312,369 'execut':798,808 'exist':222,673 'explicit':142,647,781 'extend':85,88,177,188,364,367,406 'extend-ignor':87,366,405 'extend-select':84,363 'extra':180,191 'f':421,875 'file':132,740 'find':26,104,439,451,493,501,548,702,707,764,822,833 'fix':4,35,99,200,208,462,506,512,515,550,785,821,826,847,859,870,881,886 'flexibl':65 'folder':59,130,380,416 'format':332,344,349,480,532,569,724,796 'formatt':341 'framework':624 'full':371 'gate':756 'goal':628 'guidelin':651 'highlight':791 'ignor':83,89,168,176,189,192,362,368,407,863 'impact':789 'includ':723 'inlin':114 'input':121,124,229 'instal':291,309 'intent':709 'invoc':67 'invok':308 'iter':19,49,721,801,817 'judici':111 'justif':782 'justifi':120 'keep':562 'like':395 'limit':55 'line':646 'list':823,827 'local':566 'loop':684,715,720 'm':72,152,297,384 'make':716 'manag':265 'manual':543,825 'mean':136 'minim':564 'multipl':219,585 'must':722 'narrow':642 'need':359 'next':727 'non':664 'non-obvi':663 'noqa':115,607,653,656,895 'number':815 'obvious':665 'off':748 'one':379,694 'option':9,53,76,129,141,159,169,179,190,346,351,356,436,603,679,744,813 'order':244 'outcom':672,697 'output':802 'overrid':13,81,357,388 'overview':36 'pass':100,457,497,545 'path':128,279 'per':78 'per-run':77 'perform':818 'pipx':154,313 'polici':581 'possibl':650,787 'prefer':652,681 'prefix':145,239 'present':742 'priorit':525 'proceed':596 'progress':718,731 'project':61,304,372 'project-specif':303 'prompt':841 'provid':250 'public':622 'pyproject.toml':64,376 'python':71,151,285,296,383 'qualiti':43,755 'rational':713,831 're':487,539,576 're-run':486,538,575 'readabl':627 'reason':660 'recurs':3,34,101,683,846,858,869,885 'refactor':629 'refresh':491 'remain':25,452,492,502,547,701,706,832 'remedi':544 'repeat':688,714 'repetit':102 'replac':185,195 'repo':851 'report':809 'repositori':138 'requir':108,620,703,837 'resolut':243 'resolv':24,106,231,325 'result':469,522 'return':699,761 'reusabl':236 'review':20,96,468,521,773 'ruff':2,6,33,45,66,70,73,139,143,150,153,156,206,226,232,237,247,263,271,275,281,289,298,310,315,326,377,385,402,417,460,510,760,795,812,845,857,868,884 'ruff-recursive-fix':1,844,856,867,883 'rule':12,80,157,163,167,173,181,193,396,413,617,638,737,865 'run':5,79,126,149,155,205,270,314,399,401,429,459,479,488,498,509,531,540,568,577,843,855,866,882 'runner':140,233,248 'safe':15,91,443,455,559 'scope':10,54,434,484,536,573,810 'scope/options':466,519,768 'select':82,86,158,178,361,365,412,420,433,874 'semant':473 'sensit':528 'separ':162,172 'set':62 'silent':600 'singl':645 'skill':39 'skill-ruff-recursive-fix' 'skip':390 'solut':587 'source-github' 'specif':58,305,644 'src':404 'src/data':419,888 'src/models':387,862 'starter':842 'step':590,689 'stop':317,453,686 'style':476 'suggest':840 'summar':735 'summari':819 'support':52 'suppress':118,605,609,640,666,710,777,829 'target':28,127,347,352 'td':409 'test':872 'todo':394 'todo-lik':393 'topic-agent-skills' 'topic-agents' 'topic-awesome' 'topic-custom-agents' 'topic-github-copilot' 'topic-hacktoberfest' 'topic-prompt-engineering' 'trade':747 'trade-off':746 'true':202,213,507,615 'two':668 'type':441 'unexpect':763 'unsaf':17,93,199,207,445,495,505,514,784,880 'unsafe-fix':513 'use':37,112,251,268,280,295,301,322,463,516,608,814 'user':31,217,321,594,677,752,794,838 'uv':68,148,259,267,269,400 'valid':220,586,671,743 'valu':635 'whether':203 'whole':137,850 'without':184,194,780 'workflow':50,336,424 'would':630","prices":[{"id":"b503fbe0-6b68-4195-a222-ecff2c58673f","listingId":"ea4e55b5-a803-480c-8fb6-cbdbd47fc2f1","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"github","category":"awesome-copilot","install_from":"skills.sh"},"createdAt":"2026-04-18T20:33:58.263Z"}],"sources":[{"listingId":"ea4e55b5-a803-480c-8fb6-cbdbd47fc2f1","source":"github","sourceId":"github/awesome-copilot/ruff-recursive-fix","sourceUrl":"https://github.com/github/awesome-copilot/tree/main/skills/ruff-recursive-fix","isPrimary":false,"firstSeenAt":"2026-04-18T21:51:08.555Z","lastSeenAt":"2026-05-18T18:52:24.548Z"},{"listingId":"ea4e55b5-a803-480c-8fb6-cbdbd47fc2f1","source":"skills_sh","sourceId":"github/awesome-copilot/ruff-recursive-fix","sourceUrl":"https://skills.sh/github/awesome-copilot/ruff-recursive-fix","isPrimary":true,"firstSeenAt":"2026-04-18T20:33:58.263Z","lastSeenAt":"2026-05-07T22:40:38.991Z"}],"details":{"listingId":"ea4e55b5-a803-480c-8fb6-cbdbd47fc2f1","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"github","slug":"ruff-recursive-fix","github":{"repo":"github/awesome-copilot","stars":33270,"topics":["agent-skills","agents","ai","awesome","custom-agents","github-copilot","hacktoberfest","prompt-engineering"],"license":"mit","html_url":"https://github.com/github/awesome-copilot","pushed_at":"2026-05-18T01:26:59Z","description":"Community-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.","skill_md_sha":"abc5c26882a78a107d626c0cf401b8b93bae7f98","skill_md_path":"skills/ruff-recursive-fix/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/github/awesome-copilot/tree/main/skills/ruff-recursive-fix"},"layout":"multi","source":"github","category":"awesome-copilot","frontmatter":{"name":"ruff-recursive-fix","description":"Run Ruff checks with optional scope and rule overrides, apply safe and unsafe autofixes iteratively, review each change, and resolve remaining findings with targeted edits or user decisions."},"skills_sh_url":"https://skills.sh/github/awesome-copilot/ruff-recursive-fix"},"updatedAt":"2026-05-18T18:52:24.548Z"}}