[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6PVDW1ND5DX9567440WC34J":3,"skill-same:01M6PVDW1ND5DX9567440WC34J":68},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":34,"linkOnly":35,"markdownContent":36,"markdownBody":37,"frontMatter":38,"refName":42,"commitSha":43,"skillDirectory":44,"forksCount":41,"repositoryHtmlUrl":45,"repositoryHomepageUrl":6,"ownerHtmlUrl":46,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":47,"install":48,"resources":61},"01M6PVDW1ND5DX9567440WC34J","agent-cli-guidelines",null,"Design a CLI, gate or hook whose reader is another agent. Use when building or changing one, and when a tool of yours was ignored, misread, or worked around.","muratovv\u002Fai-hats","muratovv","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F7502801?v=4","01M6JGCBN4KEJX012GPJVSH04T","Fedor Muratov","01M6JGCBSNMN7CW3RGTPPE0MN2",3,"MIT","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fagent-cli-guidelines\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33],"cli","guidelines","cli guidelines","agent cli guidelines","design","tool","reader","use","gate","hook","2026-11-10 10:12:30",false,"---\nname: agent-cli-guidelines\ndescription: >-\n  Design a CLI, gate or hook whose reader is another agent. Use when\n  building or changing one, and when a tool of yours was ignored, misread,\n  or worked around.\nlicense: MIT\nai_hats:\n  schema_version: 1\n  type: skill\n---\n\n# Agent CLI Guidelines\n\nYour reader is an agent mid-task. Give it the next step where it is standing.\n\n## When to Use\n\nUse this when you are about to write or change what a tool SAYS: a gate's\nrefusal, a hook's warning, an error path, an exit code. Use it again when a tool\nof yours was ignored or worked around — that is a defect in the tool's\ninterface, not in the reader.\n\nSkip it for output a human reads at leisure. Colour, alignment and progress bars\nare not the subject here.\n\n## Procedure\n\n### 1. Stand where the other agent is standing\n\nYou are not writing for yourself, and not for a person reading a manual. You are\nwriting for an agent that is **mid-task**, has just been interrupted by your\ntool, and wants to get back to the task. Before writing a line, answer three\nquestions as that agent:\n\n- **What did I just try to do, and what does this tell me about it?** Not the\n  tool's internal state — mine.\n- **What do I do next?** One concrete move, not a class of moves.\n- **If I do nothing, what happens to my task?** Blocked, degraded, or fine.\n\nAn agent that cannot answer these from your output will guess, and its guess is\nwhatever it was already doing.\n\n### 2. The principle: context at the point of decision\n\nEverything below is one rule applied in different places. **Put what the reader\nneeds where the decision is made** — not in a doc, not in a wiki, not in the\ntool's own `--help` two commands away. The reader has your output and the\nterminal; treat anything further away as unavailable.\n\nApplied:\n\n- a gate broke → the exact command that runs the part that broke;\n- a non-obvious exit code → what it means, in the message, not in a table\n  elsewhere;\n- a refusal → the sanctioned route, spelled out, next to the refusal;\n- a check that could not run → say so where the result is read, not in a log\n  nobody opens.\n\nWorked pairs, good and bad, with the reason each way: `examples\u002F`.\n\n### 3. Print nothing the reader cannot use\n\nYour output lands in another agent's context window and stays there. A progress\nbar, per-test dots, a banner, a re-print of the command just run — each costs the\nreader capacity and returns nothing, and the more of it there is, the further the\npart that matters drifts from where it will be seen.\n\n- **Ornament is for a tty.** Progress indicators, spinners and colour exist for a\n  human watching in real time. Emit them when the output is a terminal; a\n  non-interactive caller gets the result.\n- **Both ends are read; the middle is not.** Put the verdict first and the one\n  command last — the two positions that survive a long message. Nothing that\n  matters belongs in between, which is also the reason there should not be much\n  in between.\n\nBefore shipping, read your own output whole and ask what each line buys the\nreader. A line that does not change what the reader does next is a line you are\ncharging them for.\n\n### 4. Fire only when you should\n\nThe failure this project records is not a terse refusal — blocking guards are\nhonoured routinely. It is a guard that fires on what it should not: one that\nflags the very command it recommends, or warns on every call of a tool that is\nfine. That teaches the reader to stop reading it, and the guard that gets\nscrolled past is unavailable for the real error it was built for.\n\nA false positive is not cosmetic. It spends the reader's attention, which is the\nresource every other rule here depends on.\n\n### 5. Every remedy must run AS PRINTED\n\nThe recurring defect is not a missing remedy — it is one that does not work.\nShapes that cost real sessions here: a hint naming a verb the CLI does not have;\na refusal advising a flag the command never accepted; a recipe so incomplete\nthat following it exactly still failed; a guard instructing a form it then\nrefused; a message claiming state it had not left behind.\n\nRun your own remedy, from the state that triggers it, before shipping the\nmessage. A remedy is executable content and rots like code, not like prose.\n\n### 6. The exit code is the contract\n\n- Return the **runner's own** status, never a filter's or a wrapper's.\n- A run that produced no artifact must not exit 0 because the failure was\n  \"expected\" — a green code above a \"nothing was written\" line is a\n  contradiction the reader resolves in favour of the code.\n- A gate that cannot see the thing it judges must not report passing. A vacuous\n  green is worse than red: it is consumed as evidence.\n- Fail-open is a decision: when a check cannot run, say so where the result is\n  read and journal it — and keep the journal free of your own test traffic, or\n  it stops being readable as evidence.\n\n### 7. Say the invariant, not the catalogue\n\nA refusal that enumerates forbidden spellings teaches the reader to find an\nunlisted one, and the unlisted ones outnumber the listed. Name the property that\nmakes the action wrong; the list is illustration.\n\n### 8. Keep one home for the policy\n\nThe message the tool prints IS the documentation of its rule. Restating it in\nprose elsewhere gives it two homes and the copy drifts — and when they conflict,\nskill prose has been observed to win over the tool's own correct deny text.\nPoint at the tool; let it speak.\n\n## Completion\n\n- The three questions in step 1 are answerable from the output alone.\n- Every line was justified: the verdict is first, the command is last, and\n  nothing between them is ornament.\n- The guard fires only on what it means to catch; negative cases were checked.\n- Every printed command was executed from the failing state, and worked.\n- The exit code matches the body, and a check that could not run says so.\n- The rule has one home, and it is this output.\n\n**Validation scenario (RED).** A guard ships with a matcher that also catches a\nlegitimate spelling. It fires on nearly every session, correctly most times and\nwrongly often enough to be noise; the agent learns to scroll past it. Weeks\nlater the same guard reports a real defect, in a correctly worded and actionable\nmessage, and that message is scrolled past too. Nothing about the wording was\nwrong — the reading had already been spent.\n\n## Anti-Patterns\n\n- Writing for the tool's author instead of for an agent mid-task.\n- Spending the reader's context on progress output nobody is watching.\n- Tuning the wording of a guard that fires when it should not.\n- A refusal that explains why and not what to do.\n- A remedy nobody ran: a verb, flag, or path that does not exist.\n- Exit 0 on a run whose body says nothing was produced, or on a check that could\n  not see its subject.\n- The tool's rule restated in prose that will drift from it.\n","# Agent CLI Guidelines\n\nYour reader is an agent mid-task. Give it the next step where it is standing.\n\n## When to Use\n\nUse this when you are about to write or change what a tool SAYS: a gate's\nrefusal, a hook's warning, an error path, an exit code. Use it again when a tool\nof yours was ignored or worked around — that is a defect in the tool's\ninterface, not in the reader.\n\nSkip it for output a human reads at leisure. Colour, alignment and progress bars\nare not the subject here.\n\n## Procedure\n\n### 1. Stand where the other agent is standing\n\nYou are not writing for yourself, and not for a person reading a manual. You are\nwriting for an agent that is **mid-task**, has just been interrupted by your\ntool, and wants to get back to the task. Before writing a line, answer three\nquestions as that agent:\n\n- **What did I just try to do, and what does this tell me about it?** Not the\n  tool's internal state — mine.\n- **What do I do next?** One concrete move, not a class of moves.\n- **If I do nothing, what happens to my task?** Blocked, degraded, or fine.\n\nAn agent that cannot answer these from your output will guess, and its guess is\nwhatever it was already doing.\n\n### 2. The principle: context at the point of decision\n\nEverything below is one rule applied in different places. **Put what the reader\nneeds where the decision is made** — not in a doc, not in a wiki, not in the\ntool's own `--help` two commands away. The reader has your output and the\nterminal; treat anything further away as unavailable.\n\nApplied:\n\n- a gate broke → the exact command that runs the part that broke;\n- a non-obvious exit code → what it means, in the message, not in a table\n  elsewhere;\n- a refusal → the sanctioned route, spelled out, next to the refusal;\n- a check that could not run → say so where the result is read, not in a log\n  nobody opens.\n\nWorked pairs, good and bad, with the reason each way: `examples\u002F`.\n\n### 3. Print nothing the reader cannot use\n\nYour output lands in another agent's context window and stays there. A progress\nbar, per-test dots, a banner, a re-print of the command just run — each costs the\nreader capacity and returns nothing, and the more of it there is, the further the\npart that matters drifts from where it will be seen.\n\n- **Ornament is for a tty.** Progress indicators, spinners and colour exist for a\n  human watching in real time. Emit them when the output is a terminal; a\n  non-interactive caller gets the result.\n- **Both ends are read; the middle is not.** Put the verdict first and the one\n  command last — the two positions that survive a long message. Nothing that\n  matters belongs in between, which is also the reason there should not be much\n  in between.\n\nBefore shipping, read your own output whole and ask what each line buys the\nreader. A line that does not change what the reader does next is a line you are\ncharging them for.\n\n### 4. Fire only when you should\n\nThe failure this project records is not a terse refusal — blocking guards are\nhonoured routinely. It is a guard that fires on what it should not: one that\nflags the very command it recommends, or warns on every call of a tool that is\nfine. That teaches the reader to stop reading it, and the guard that gets\nscrolled past is unavailable for the real error it was built for.\n\nA false positive is not cosmetic. It spends the reader's attention, which is the\nresource every other rule here depends on.\n\n### 5. Every remedy must run AS PRINTED\n\nThe recurring defect is not a missing remedy — it is one that does not work.\nShapes that cost real sessions here: a hint naming a verb the CLI does not have;\na refusal advising a flag the command never accepted; a recipe so incomplete\nthat following it exactly still failed; a guard instructing a form it then\nrefused; a message claiming state it had not left behind.\n\nRun your own remedy, from the state that triggers it, before shipping the\nmessage. A remedy is executable content and rots like code, not like prose.\n\n### 6. The exit code is the contract\n\n- Return the **runner's own** status, never a filter's or a wrapper's.\n- A run that produced no artifact must not exit 0 because the failure was\n  \"expected\" — a green code above a \"nothing was written\" line is a\n  contradiction the reader resolves in favour of the code.\n- A gate that cannot see the thing it judges must not report passing. A vacuous\n  green is worse than red: it is consumed as evidence.\n- Fail-open is a decision: when a check cannot run, say so where the result is\n  read and journal it — and keep the journal free of your own test traffic, or\n  it stops being readable as evidence.\n\n### 7. Say the invariant, not the catalogue\n\nA refusal that enumerates forbidden spellings teaches the reader to find an\nunlisted one, and the unlisted ones outnumber the listed. Name the property that\nmakes the action wrong; the list is illustration.\n\n### 8. Keep one home for the policy\n\nThe message the tool prints IS the documentation of its rule. Restating it in\nprose elsewhere gives it two homes and the copy drifts — and when they conflict,\nskill prose has been observed to win over the tool's own correct deny text.\nPoint at the tool; let it speak.\n\n## Completion\n\n- The three questions in step 1 are answerable from the output alone.\n- Every line was justified: the verdict is first, the command is last, and\n  nothing between them is ornament.\n- The guard fires only on what it means to catch; negative cases were checked.\n- Every printed command was executed from the failing state, and worked.\n- The exit code matches the body, and a check that could not run says so.\n- The rule has one home, and it is this output.\n\n**Validation scenario (RED).** A guard ships with a matcher that also catches a\nlegitimate spelling. It fires on nearly every session, correctly most times and\nwrongly often enough to be noise; the agent learns to scroll past it. Weeks\nlater the same guard reports a real defect, in a correctly worded and actionable\nmessage, and that message is scrolled past too. Nothing about the wording was\nwrong — the reading had already been spent.\n\n## Anti-Patterns\n\n- Writing for the tool's author instead of for an agent mid-task.\n- Spending the reader's context on progress output nobody is watching.\n- Tuning the wording of a guard that fires when it should not.\n- A refusal that explains why and not what to do.\n- A remedy nobody ran: a verb, flag, or path that does not exist.\n- Exit 0 on a run whose body says nothing was produced, or on a check that could\n  not see its subject.\n- The tool's rule restated in prose that will drift from it.\n",{"name":5,"ai_hats":39,"license":15,"description":7},{"type":40,"schema_version":41},"skill",1,"master","f922a7f627276366873d546942d9ad899a86f71a","packages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fagent-cli-guidelines","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats","https:\u002F\u002Fgithub.com\u002Fmuratovv","2026-11-05 20:59:10",{"source":8,"skillName":5,"commands":49,"prompt":59,"zipAvailable":60},[50,53,56],{"tool":51,"command":52},"npx","npx skills add muratovv\u002Fai-hats --skill agent-cli-guidelines",{"tool":54,"command":55},"bunx","bunx skills add muratovv\u002Fai-hats --skill agent-cli-guidelines",{"tool":57,"command":58},"pnpm","pnpm dlx skills add muratovv\u002Fai-hats --skill agent-cli-guidelines","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fagent-cli-guidelines\u002FSKILL.md",true,[62],{"path":63,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":66,"sourceHtmlUrl":67},"examples\u002Fgood-and-bad.md","REFERENCE","参考文档",4981,"https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fagent-cli-guidelines\u002Fexamples\u002Fgood-and-bad.md",[69,94,119,138,162,174],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":34},"01M6PVFB1SM738R2SRSRSF7CY6","tool-evaluation-protocol","Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML\u002FLLM frameworks, testing approaches), or following up on a hype-driven recommendation.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Ftool-evaluation-protocol\u002FSKILL.md",[],[76,77,29,78,79,80,81,82,83,84,31,85,86,87,88,89,90,91,92,93],"protocol","Evaluation","tool evaluation protocol","testing","ml","libraries","adoption","methodology","Tools","dependency","up","frameworks","time","project","recommendation","for","bounded","candidate",{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":34},"01M6PVF7HATBEX1G7N50E2QT57","systematic-debugging","4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fsystematic-debugging\u002FSKILL.md",[],[101,102,103,104,76,105,106,107,108,109,31,110,111,112,113,114,115,116,117,118],"systematic debugging","debugging","systematic","test","monitoring","hypothesis","verify","behavior","fix","evidence","bug","reports","pattern","users","error","with","bug-fix","phase",{"skillNo":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":123,"categories":124,"keywords":126,"publishedAt":34},"01M6PVF3MTQN3RPF73AN34856J","skill-template","Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fskill-template\u002FSKILL.md",[125],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[127,128,129,130,131,108,132,31,133,113,134,135,136,91,137],"template","skill template","validation","compliance","hats","guide","new skill","structural","canonical","which","Existing",{"skillNo":139,"name":140,"nameZh":6,"description":141,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":142,"categories":143,"keywords":145,"publishedAt":34},"01M6PVF06SCV28QARM5MQPANC9","skill-optimization","Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fskill-optimization\u002FSKILL.md",[144],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[146,147,148,149,150,151,152,153,154,155,31,156,157,158,159,160,161],"Optimization","skill optimization","components","component","issues","library","audit","refactor","Budget","Rules","periodic","maintenance","token","token budget","role","high",{"skillNo":163,"name":164,"nameZh":6,"description":165,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":166,"categories":167,"keywords":168,"publishedAt":34},"01M6PVEXM9717016T9MW82HDCT","silent-fallback-gate","PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fsilent-fallback-gate\u002FSKILL.md",[],[32,169,170,171,172,173,31,33,91],"fallback","silent fallback gate","python","write","edit",{"skillNo":175,"name":176,"nameZh":6,"description":177,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":178,"categories":179,"keywords":181,"publishedAt":34},"01M6PVESM49C5NT7SB7N3F76VS","retro-to-framework","Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fretro-to-framework\u002FSKILL.md",[180],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[182,183,184,185,149,186,187,188,155,108,31,189,190,89,191,192,193,194,195,196],"framework","retro","retro to framework","change","retrospective","projects","convert","incident","across","problem","about","more","skill update","single","generic"]