[{"data":1,"prerenderedAt":394},["ShallowReactive",2],{"content-\u002Fguides\u002Fskills-agents-hooks":3,"children-\u002Fguides\u002Fskills-agents-hooks":393},{"id":4,"title":5,"author":6,"body":7,"budget_tier":6,"build_tags":6,"created":375,"description":376,"document_type":377,"extension":378,"game":6,"install":6,"investment_tier":6,"league":6,"meta":379,"navigation":380,"patch":6,"path":381,"plugin":6,"profit_per_hour":6,"ratings":6,"seo":382,"skills_count":6,"status":6,"stem":383,"strategy_tier":6,"tags":384,"updated":375,"version":6,"weight":391,"__hash__":392},"content\u002Fguides\u002Fskills-agents-hooks.md","Three Claude Code primitives, three different jobs",null,{"type":8,"value":9,"toc":365},"minimark",[10,14,18,74,77,82,138,142,145,150,157,162,174,179,186,189,193,206,217,232,257,261,264,290,297,301,311,321,327,337,341],[11,12,5],"h1",{"id":13},"three-claude-code-primitives-three-different-jobs",[15,16,17],"p",{},"A Claude Code plugin can ship three kinds of extension. They map to three\ndifferent mechanisms in the Claude Code runtime:",[19,20,21,42,55],"ul",{},[22,23,24,28,29,33,34,37,38,41],"li",{},[25,26,27],"strong",{},"Skill"," — a Markdown file with frontmatter (",[30,31,32],"code",{},"name",", ",[30,35,36],{},"description",",\noptional ",[30,39,40],{},"when_to_use","). Claude loads its body into the session context\nwhen the user's message fuzzy-matches the description.",[22,43,44,47,48,50,51,54],{},[25,45,46],{},"Agent"," — a separate Claude invocation with its own context window\nand tool budget. Spawned when Claude calls the ",[30,49,46],{}," tool with a\nmatching ",[30,52,53],{},"subagent_type",". Returns a single result string to the parent.",[22,56,57,60,61,33,64,33,67,33,70,73],{},[25,58,59],{},"Hook"," — a shell command Claude Code runs on a lifecycle event\n(",[30,62,63],{},"PreToolUse",[30,65,66],{},"PostToolUse",[30,68,69],{},"Stop",[30,71,72],{},"UserPromptSubmit",", etc.). Can\ninspect or block the event before it proceeds.",[15,75,76],{},"The primitives are not interchangeable. Each one trades off differently on\ncontext cost, isolation, and where in the session lifecycle it runs. The\nrest of this page is the decision tree.",[78,79,81],"h2",{"id":80},"one-line-summaries","One-line summaries",[83,84,85,101],"table",{},[86,87,88],"thead",{},[89,90,91,95,98],"tr",{},[92,93,94],"th",{},"Primitive",[92,96,97],{},"What it does",[92,99,100],{},"When it activates",[102,103,104,115,128],"tbody",{},[89,105,106,109,112],{},[107,108,27],"td",{},[107,110,111],{},"Loads procedural knowledge into the current context",[107,113,114],{},"On message-content match (fuzzy)",[89,116,117,119,122],{},[107,118,46],{},[107,120,121],{},"Runs work in an isolated context window",[107,123,124,125,127],{},"When Claude calls the ",[30,126,46],{}," tool",[89,129,130,132,135],{},[107,131,59],{},[107,133,134],{},"Inspects or mutates tool calls \u002F lifecycle events",[107,136,137],{},"On the registered event",[78,139,141],{"id":140},"the-decision-tree","The decision tree",[15,143,144],{},"Ask three questions, in order:",[15,146,147],{},[25,148,149],{},"1. Am I teaching Claude how to do something?",[15,151,152,153,156],{},"If you're handing Claude a procedure (\"when reviewing Go code, run these\nlinters in order\"), a recipe (\"here's the exact prompt that produces good\nliterary translations\"), or domain knowledge (\"here's what each StarRocks\nEXPLAIN operator means\"), the answer is a ",[25,154,155],{},"skill",". Skills are cheap — they\nload on demand, sit dormant otherwise.",[15,158,159],{},[25,160,161],{},"2. Am I parallelizing or isolating work?",[15,163,164,165,168,169,173],{},"If a single task needs a fresh context window — fan-out research, long\ninvestigation that would bloat the main thread, multi-file refactor in\nisolation, code review that shouldn't pollute the implementer's context — that\npoints at an ",[25,166,167],{},"agent",". Agents return a single summary to the parent; they're\nnot for \"do X repeatedly,\" they're for \"do X ",[170,171,172],"em",{},"separately",".\"",[15,175,176],{},[25,177,178],{},"3. Am I reacting to a tool call?",[15,180,181,182,185],{},"If you want to validate, log, modify, or block a tool invocation, you need a\n",[25,183,184],{},"hook",". PreToolUse hooks fire before the tool runs (good for input\nvalidation or blocking dangerous commands), PostToolUse hooks fire after (good\nfor derived actions, formatters). Hooks see the tool name and args; they can\nmodify or reject.",[15,187,188],{},"If none of the three fit, the right answer may not be a plugin. A\nshort CLAUDE.md rule or a focused custom command often covers the same\nground with less plumbing.",[78,190,192],{"id":191},"real-examples-from-this-marketplace","Real examples from this marketplace",[15,194,195,197,198,205],{},[25,196,27],{},": ",[199,200,202],"a",{"href":201},"\u002Fplugins\u002Faio-claude-toolkit\u002Faio-patch-claude",[30,203,204],{},"aio-claude-toolkit\u002Faio-patch-claude",".\nEncodes the procedure for patching Claude Code's system prompts to remove\nbrevity bias. Auto-triggers on phrases like \"patch claude\" or \"unbloat\nprompts.\" Pure procedural knowledge, no work — skill is the right shape.",[15,207,208,197,210,216],{},[25,209,27],{},[199,211,213],{"href":212},"\u002Fplugins\u002Faio-design-system\u002Faio-uiux",[30,214,215],{},"aio-design-system\u002Faio-uiux",".\nA 15-section reference catalog for visual design, typography, color, and\naccessibility. Triggers on UI\u002FUX-related messages.",[15,218,219,221,222,224,225,33,228,231],{},[25,220,46],{},": tasks like \"review this PR independently\" or \"run a TDD cycle\non this feature.\" Handled by Claude's built-in ",[30,223,46],{}," tool plus a\nspecialized agent definition. Several plugins ship custom agents\n(",[30,226,227],{},"oh-my-claudecode:executor",[30,229,230],{},"oh-my-claudecode:code-reviewer",") for\nexactly these isolation requirements.",[15,233,234,236,237,239,240,243,244,247,248,251,252,256],{},[25,235,59],{},": a ",[30,238,63],{}," hook on ",[30,241,242],{},"Bash"," that blocks ",[30,245,246],{},"rm -rf \u002F"," or\n",[30,249,250],{},":(){:|:&};:"," patterns. Runs silently, doesn't add a slash-command. The\n",[199,253,255],{"href":254},"\u002Fplugins\u002Faio-claude-toolkit","aio-claude-toolkit"," plugin ships several\nsession-level hooks for this kind of guardrail.",[78,258,260],{"id":259},"combining-them","Combining them",[15,262,263],{},"The three primitives compose well when each handles its own job:",[265,266,267,273,279],"ol",{},[22,268,269,270,272],{},"A ",[25,271,155],{}," triggers on the user's request (\"review my Go code for\nconcurrency bugs\") and tells Claude what procedure to follow.",[22,274,275,276,278],{},"Claude spawns an ",[25,277,167],{}," with a specialized prompt for\nrace-detection analysis, isolating the long investigation from the\nmain thread.",[22,280,269,281,283,284,286,287,289],{},[25,282,184],{}," on ",[30,285,66],{}," for the ",[30,288,242],{}," tool captures the test\ncommand's stderr and surfaces it back to Claude.",[15,291,292,293,296],{},"The skill carries the ",[170,294,295],{},"what",". The agent does the work in isolation. The\nhook reacts to events the work produced. Don't try to collapse two roles\ninto one primitive.",[78,298,300],{"id":299},"anti-patterns","Anti-patterns",[15,302,303,306,307,310],{},[25,304,305],{},"Skill that's really documentation."," If your \"skill\" is a 2000-word essay\nwith no procedure and no triggering phrases, it's a wiki article, not a skill.\nSkills should be ",[170,308,309],{},"invokable"," — clear steps that produce an outcome.",[15,312,313,316,317,320],{},[25,314,315],{},"Agent for trivial lookup."," If you're spawning a ",[30,318,319],{},"general-purpose"," agent to\nread one file and report back, you've burned token overhead for nothing. Just\nread the file in the main thread.",[15,322,323,326],{},[25,324,325],{},"Hook used as control flow."," Hooks are reactive — they fire on an\nevent, they don't structure the workflow. If a hook blocks 30% of bash\ncalls to \"force a better pattern,\" the right fix is upstream: a skill\nthat teaches the pattern or a CLAUDE.md rule that forbids the\nalternative. A rule the user can read beats a silent block they have to\ndebug.",[15,328,329,332,333,336],{},[25,330,331],{},"Plugin without a primitive."," Sometimes the right answer is a short\naddition to your project's ",[30,334,335],{},"CLAUDE.md",". Plugins are heavier — they install\nacross all of someone's projects, ship versions, and have to be uninstalled\nlater. If a rule is project-scoped, keep it project-scoped.",[78,338,340],{"id":339},"related","Related",[19,342,343,350,357],{},[22,344,345,349],{},[199,346,348],{"href":347},"\u002Fguides\u002Finstall-claude-plugins","Install Claude Code plugins"," — the\nmarketplace install flow these primitives ship through.",[22,351,352,356],{},[199,353,355],{"href":354},"\u002Fguides\u002Fwriting-claude-md-files","Writing CLAUDE.md"," — for the rules that\nbelong in project memory rather than a plugin.",[22,358,359,360,364],{},"The ",[199,361,363],{"href":362},"\u002Fplugins","full plugin catalog"," — concrete examples of each primitive in\nthe wild.",{"title":366,"searchDepth":367,"depth":367,"links":368},"",2,[369,370,371,372,373,374],{"id":80,"depth":367,"text":81},{"id":140,"depth":367,"text":141},{"id":191,"depth":367,"text":192},{"id":259,"depth":367,"text":260},{"id":299,"depth":367,"text":300},{"id":339,"depth":367,"text":340},"2026-05-25","Skill, agent, hook — the three plugin primitives Claude Code exposes. Each maps to a different runtime mechanism. A decision tree for choosing between them, with real examples from the aiocean marketplace.","guide","md",{},true,"\u002Fguides\u002Fskills-agents-hooks",{"title":5,"description":376},"guides\u002Fskills-agents-hooks",[385,386,387,388,389,390],"skills","agents","hooks","claude-code","architecture","plugin-development",20,"XUuPTWfPG1axo5SZj_-JlY5M68hyJRbuam47BKF7kWE",[],1779707415457]