{"id":"2c7c5d52-db8a-495e-b7a9-868704f1793f","shortId":"vnnbsB","kind":"skill","title":"context-engineer","tagline":"Optimize what loads into the agent's context — what to include, what to drop, how to recover when output quality degrades. Use when starting a new session on a complex task, when agent output starts inventing APIs or diverging from conventions, when switching between tasks, or wh","description":"# Context Engineer\n\nContext is the agent's working memory. Bad context produces hallucinated APIs, ignored conventions, and repeated mistakes. Good context produces tight, conventional, on-target output. This skill is the discipline of deciding what loads, in what order, and what to drop when quality degrades.\n\nThis skill mirrors `~/.claude/rules/context-engineering.md`. Keep both in sync when updating.\n\n## Hierarchy (load in this order)\n\n1. **Rules** — persistent, project-wide conventions (always loaded: AGENTS.md, CLAUDE.md, `~/.claude/rules/`)\n2. **Specs / PRDs** — per-feature requirements and constraints (the `.specs/<slug>.md` for the current task)\n3. **Relevant source** — files directly related to the task (not \"all files in the module\")\n4. **Error output** — current failures and stack traces (the exact ones, not paraphrased)\n5. **Conversation history** — managed by compaction; oldest goes first when truncating\n\nThe order matters. Rules anchor everything. Specs scope. Source grounds. Errors guide. History contextualizes.\n\n## Principles\n\n- **Quality over quantity**: focused context (<2000 lines) outperforms comprehensive dumps. The agent reads what's loaded; it doesn't skim.\n- **Just-in-time loading**: pull a file when its content matters, not \"just in case\". Reference by path until needed.\n- **Drop completed work**: once a sub-task is done, summarize it and let the intermediate steps fall out of context.\n- **Path beats paste**: reference `src/auth/session.ts:42` instead of pasting the function. The agent can re-read on demand.\n\n## Session start protocol\n\nBefore non-trivial work:\n\n1. State the goal in one sentence\n2. Load the rules layer: AGENTS.md / CLAUDE.md + relevant `~/.claude/rules/*.md`\n3. Load the spec / PRD if one exists for this task\n4. Identify ~3-7 files most relevant to the task; load by reference, not full content\n5. State assumptions; ask the user to correct any wrong assumption before proceeding\n\nIf you can't fit the above in <30% of the context window, the task is too big — break it into smaller conversations.\n\n## Red flags — context is failing\n\nWatch for these signals. They are silent until you look:\n\n- Agent invents APIs, function names, or flags that don't exist\n- Output diverges from documented conventions even though the rule is loaded\n- Quality degrades as conversation lengthens (later answers worse than earlier)\n- Agent asks questions already answered in loaded context\n- Same mistake repeats after correction\n- Agent confabulates citations to lines or files that don't exist\n\nWhen you see any of these, stop and recover.\n\n## Recovery\n\nIn order of cost:\n\n1. **Re-state the rule / fact** explicitly in the current turn — cheapest, often enough\n2. **`/clear`** between unrelated tasks — frees context, re-loads rules at next message\n3. **Re-load rules and the most relevant 2-3 files** explicitly after compaction\n4. **Break large tasks into smaller conversations** — each conversation focused, rules re-loaded\n5. **When quality drops mid-conversation**: stop, summarize current state into a note, start a fresh session pointed at the note\n\nDo not push through degraded context. The cost of one fresh session is less than the cost of one wrong commit caused by drift.\n\n## Task switching\n\nWhen pivoting from task A to task B:\n\n- If the tasks share rules and source files → keep the session, state the pivot\n- If the tasks are independent → `/clear` and start fresh; the new task pays a tiny cold-start cost in exchange for clean context\n- Default to `/clear` when in doubt — fresh context is almost free; degraded context is expensive\n\nSign you switched too aggressively: agent answers task B with patterns from task A.\n\n## What NOT to preload\n\n- Entire directories (\"just so you have the codebase\")\n- Generated code (lock files, dist/, build artifacts)\n- Documentation pages \"in case they come up\"\n- Test files when fixing production code (load only the test for the case being fixed)\n- Historical commits beyond what's needed to understand the current state\n\nPreloading \"just in case\" reads token budget you'll need later.\n\n## Rules\n\n- Load rules first, then specs, then source, then errors\n- Keep total loaded context <2000 lines when possible; always <30% of window\n- Reference by path until the content is actually needed\n- Watch for red flags every ~10 turns in long sessions\n- Recover via `/clear` early, not late\n- Never paste large files when you can reference them\n\n## Red flags (meta — when this skill is misapplied)\n\n- Loading this skill itself into context for trivial tasks (it's overhead)\n- Following the session-start protocol for one-line fixes (ceremony over speed)\n- Re-loading rules every turn (rules are sticky once loaded; only re-load after `/clear` or compaction)\n\n## Verification\n\nWhen applied to a non-trivial task:\n\n- [ ] Goal stated in one sentence before loading anything\n- [ ] Rules layer loaded explicitly\n- [ ] Spec / PRD loaded if it exists\n- [ ] Relevant source identified by path; only loaded when needed\n- [ ] Assumptions stated; user confirmed or corrected before implementing\n- [ ] If output quality degrades mid-session: recover, do not push through","tags":["context","engineer","agent","skills","helderberto","agent-skills","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli"],"capabilities":["skill","source-helderberto","skill-context-engineer","topic-agent-skills","topic-ai-tools","topic-antigravity","topic-claude-code","topic-cursor","topic-developer-tools","topic-gemini-cli","topic-markdown","topic-plugin","topic-sdlc","topic-skills","topic-tracer-bullet"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/helderberto/agent-skills/context-engineer","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add helderberto/agent-skills","source_repo":"https://github.com/helderberto/agent-skills","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 (5,156 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:09:12.472Z","embedding":null,"createdAt":"2026-05-18T13:14:52.391Z","updatedAt":"2026-05-18T19:09:12.472Z","lastSeenAt":"2026-05-18T19:09:12.472Z","tsv":"'-3':488 '-7':315 '/.claude/rules':124,299 '/.claude/rules/context-engineering.md':101 '/clear':465,582,603,736,799 '1':113,284,449 '10':729 '2':125,291,464,487 '2000':200,707 '3':141,301,314,478 '30':349,712 '4':156,312,493 '42':262 '5':169,328,507 'actual':722 'agent':9,36,56,206,269,379,411,424,621 'agents.md':122,296 'aggress':620 'almost':610 'alreadi':414 'alway':120,711 'anchor':184 'answer':407,415,622 'anyth':818 'api':40,64,381 'appli':804 'artifact':648 'ask':331,412 'assumpt':330,338,838 'b':562,624 'bad':60 'beat':258 'beyond':673 'big':358 'break':359,494 'budget':688 'build':647 'case':230,652,668,685 'caus':550 'ceremoni':780 'cheapest':461 'citat':426 'claude.md':123,297 'clean':599 'code':643,661 'codebas':641 'cold':593 'cold-start':592 'come':654 'commit':549,672 'compact':174,492,801 'complet':237 'complex':33 'comprehens':203 'confabul':425 'confirm':841 'constraint':133 'content':225,327,720 'context':2,11,51,53,61,71,199,256,352,366,418,470,534,600,608,613,706,762 'context-engin':1 'contextu':193 'convent':44,66,74,119,394 'convers':170,363,404,499,501,513 'correct':335,423,843 'cost':448,536,545,595 'current':139,159,459,516,680 'decid':85 'default':601 'degrad':24,97,402,533,612,849 'demand':275 'direct':145 'directori':635 'disciplin':83 'dist':646 'diverg':42,391 'document':393,649 'doesn':212 'done':245 'doubt':606 'drift':552 'drop':17,94,236,510 'dump':204 'earli':737 'earlier':410 'engin':3,52 'enough':463 'entir':634 'error':157,190,702 'even':395 'everi':728,787 'everyth':185 'exact':165 'exchang':597 'exist':308,389,434,828 'expens':615 'explicit':456,490,822 'fact':455 'fail':368 'failur':160 'fall':253 'featur':130 'file':144,152,222,316,430,489,570,645,657,743 'first':177,696 'fit':345 'fix':659,670,779 'flag':365,385,727,750 'focus':198,502 'follow':769 'free':469,611 'fresh':523,539,585,607 'full':326 'function':267,382 'generat':642 'goal':287,811 'goe':176 'good':70 'ground':189 'guid':191 'hallucin':63 'hierarchi':108 'histor':671 'histori':171,192 'identifi':313,831 'ignor':65 'implement':845 'includ':14 'independ':581 'instead':263 'intermedi':251 'invent':39,380 'just-in-tim':215 'keep':102,571,703 'larg':495,742 'late':739 'later':406,692 'layer':295,820 'lengthen':405 'less':542 'let':249 'line':201,428,708,778 'll':690 'load':6,87,109,121,210,219,292,302,322,400,417,473,481,506,662,694,705,757,785,793,797,817,821,825,835 'lock':644 'long':732 'look':378 'manag':172 'matter':182,226 'md':136,300 'memori':59 'messag':477 'meta':751 'mid':512,851 'mid-convers':511 'mid-sess':850 'mirror':100 'misappli':756 'mistak':69,420 'modul':155 'name':383 'need':235,676,691,723,837 'never':740 'new':29,587 'next':476 'non':281,808 'non-trivi':280,807 'note':520,528 'often':462 'oldest':175 'on-target':75 'one':166,289,307,538,547,777,814 'one-lin':776 'optim':4 'order':90,112,181,446 'outperform':202 'output':22,37,78,158,390,847 'overhead':768 'page':650 'paraphras':168 'past':259,265,741 'path':233,257,717,833 'pattern':626 'pay':589 'per':129 'per-featur':128 'persist':115 'pivot':556,576 'point':525 'possibl':710 'prd':305,824 'prds':127 'preload':633,682 'principl':194 'proceed':340 'produc':62,72 'product':660 'project':117 'project-wid':116 'protocol':278,774 'pull':220 'push':531,856 'qualiti':23,96,195,401,509,848 'quantiti':197 'question':413 're':272,451,472,480,505,784,796 're-load':471,479,504,783,795 're-read':271 're-stat':450 'read':207,273,686 'recov':20,443,734,853 'recoveri':444 'red':364,726,749 'refer':231,260,324,715,747 'relat':146 'relev':142,298,318,486,829 'repeat':68,421 'requir':131 'rule':114,183,294,398,454,474,482,503,567,693,695,786,789,819 'scope':187 'see':437 'sentenc':290,815 'session':30,276,524,540,573,733,772,852 'session-start':771 'share':566 'sign':616 'signal':372 'silent':375 'skill':80,99,754,759 'skill-context-engineer' 'skim':214 'smaller':362,498 'sourc':143,188,569,700,830 'source-helderberto' 'spec':126,135,186,304,698,823 'speed':782 'src/auth/session.ts':261 'stack':162 'start':27,38,277,521,584,594,773 'state':285,329,452,517,574,681,812,839 'step':252 'sticki':791 'stop':441,514 'sub':242 'sub-task':241 'summar':246,515 'switch':46,554,618 'sync':105 'target':77 'task':34,48,140,149,243,311,321,355,468,496,553,558,561,565,579,588,623,628,765,810 'test':656,665 'though':396 'tight':73 'time':218 'tini':591 'token':687 'topic-agent-skills' 'topic-ai-tools' 'topic-antigravity' 'topic-claude-code' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'topic-markdown' 'topic-plugin' 'topic-sdlc' 'topic-skills' 'topic-tracer-bullet' 'total':704 'trace':163 'trivial':282,764,809 'truncat':179 'turn':460,730,788 'understand':678 'unrel':467 'updat':107 'use':25 'user':333,840 'verif':802 'via':735 'watch':369,724 'wh':50 'wide':118 'window':353,714 'work':58,238,283 'wors':408 'wrong':337,548","prices":[{"id":"6350986b-04a3-4e8a-868f-feb5c51c43d3","listingId":"2c7c5d52-db8a-495e-b7a9-868704f1793f","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"helderberto","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:14:52.391Z"}],"sources":[{"listingId":"2c7c5d52-db8a-495e-b7a9-868704f1793f","source":"github","sourceId":"helderberto/agent-skills/context-engineer","sourceUrl":"https://github.com/helderberto/agent-skills/tree/main/skills/context-engineer","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:52.391Z","lastSeenAt":"2026-05-18T19:09:12.472Z"}],"details":{"listingId":"2c7c5d52-db8a-495e-b7a9-868704f1793f","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"helderberto","slug":"context-engineer","github":{"repo":"helderberto/agent-skills","stars":8,"topics":["agent-skills","ai","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli","markdown","plugin","sdlc","skills","tracer-bullet"],"license":"mit","html_url":"https://github.com/helderberto/agent-skills","pushed_at":"2026-05-14T11:37:47Z","description":"My personal SDLC toolbelt for AI coding agents — PRD to ship.","skill_md_sha":"4c0103d6d5ee9c0ff521918bbeda50a16751d92d","skill_md_path":"skills/context-engineer/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/helderberto/agent-skills/tree/main/skills/context-engineer"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"context-engineer","description":"Optimize what loads into the agent's context — what to include, what to drop, how to recover when output quality degrades. Use when starting a new session on a complex task, when agent output starts inventing APIs or diverging from conventions, when switching between tasks, or when context is approaching the window limit. Don't use for trivial single-file tasks where context is obvious."},"skills_sh_url":"https://skills.sh/helderberto/agent-skills/context-engineer"},"updatedAt":"2026-05-18T19:09:12.472Z"}}