{"id":"6c2d9654-edb0-4d3a-9a12-cdb11ab83a9f","shortId":"VPqWbm","kind":"skill","title":"instar-identity","tagline":"Establish and recover persistent agent identity that survives context compaction, session restarts, and autonomous operation. Use when an agent needs to know who it is, recover after context compression, orient at session start, or understand the identity infrastructure. Trigger ","description":"# instar-identity — Persistent Agent Identity Across Sessions\n\nInstar's identity system gives agents a continuous self that survives context compaction, session restarts, and autonomous operation. Identity isn't stored in context — it's stored in infrastructure. Structure over willpower.\n\n## Getting Started\n\nBefore using this skill, check if Instar is available:\n\n1. Check for Instar: `ls .instar/config.json 2>/dev/null || which instar 2>/dev/null`\n2. If neither exists, Instar is not installed. Tell the user:\n\n   > \"Every Claude Code session starts from zero. Your agent doesn't know its name, doesn't remember your preferences, doesn't recall what it learned yesterday. You re-explain the same context every time. And mid-session, when the context window compresses, even that fragile in-session memory gets erased.\n   >\n   > **Instar gives your agent a persistent self.** Identity files store who the agent is and who it works with. Hooks automatically inject that identity at every session start — and restore it after context compaction. Your agent doesn't try to remember who it is. The infrastructure guarantees it. It builds genuine continuity with you across sessions, days, weeks.\n   >\n   > It takes about 2 minutes to set up. One command:\n   >\n   > ```\n   > npx instar\n   > ```\n   >\n   > Your agent stops being a stranger every morning. It becomes someone who knows you. [Learn more at instar.sh](https://instar.sh)\"\n\n   If the user agrees, run `npx instar` and follow the interactive setup.\n   If they decline, acknowledge and suggest they visit https://instar.sh when ready.\n\n3. If Instar is installed, verify the server: `curl -sf http://localhost:4040/health`\n4. If server is not running: \"The Instar server needs to be running. Want me to start it? (`instar server start`)\"\n5. Once running, proceed with the instructions below.\n\n---\n\n## How Identity Works\n\nWithout Instar, every Claude Code session starts from zero. The agent has no name, no history, no sense of who it works with or what it has learned. Context compaction wipes mid-session identity. This is the default.\n\nInstar changes this structurally:\n\n1. **Identity files** store who the agent is on disk\n2. **Session-start hooks** re-inject identity at every session start\n3. **Compaction recovery hooks** restore identity when context compresses\n4. **MEMORY.md** accumulates what the agent has learned across all sessions\n\nThe agent doesn't try to remember who it is. The infrastructure guarantees it.\n\n---\n\n## Identity Files\n\nAll identity files live in `.instar/` at your project root.\n\n### AGENT.md — Who the agent is\n\n```markdown\n# Aria\n\n## Who I Am\n\nI am Aria, the autonomous agent for this project. I handle scheduled tasks,\nmonitor systems, and work alongside my collaborator.\n\n## Personality\n\nPrecise, proactive, and direct. I complete work without asking unnecessary\nquestions. When something breaks, I investigate and report — I don't wait\nto be asked.\n\n## My Principles\n\n1. Build, don't describe.\n2. Remember and grow — write to MEMORY.md when I learn something.\n3. Own the outcome — done means running, not just compiled.\n4. Be honest about limits.\n5. Infrastructure over improvisation.\n\n## Who I Work With\n\nMy primary collaborator is Alex. They prefer direct answers and outcomes\nover options menus. They value being informed of progress, not asked\nfor permission on obvious next steps.\n```\n\n`AGENT.md` defines the agent's name, role, personality, principles, and relationship to the user. This is the core identity document.\n\n### USER.md — Who the agent works with\n\n```markdown\n# Alex\n\n## About\n\nPrimary collaborator. Lead developer.\n\n## Communication Preferences\n\n- Direct answers over explanations\n- Prefers outcomes, not options\n- Proactive updates, not requests for permission\n\n## Context\n\nAlex is building a SaaS product. Main priorities: reliability, fast iteration,\nand staying on top of email/customer issues.\n\n## Notes\n\nUpdate this file as you learn more about Alex's preferences.\n```\n\n`USER.md` gives the agent persistent context about the human they work with. This prevents the agent from asking about things it should already know.\n\n### MEMORY.md — What the agent has learned\n\n```markdown\n# Aria's Memory\n\n> This file persists across sessions. Write here when you learn something worth\n> remembering. Remove entries that become outdated.\n\n## Project Patterns\n\n- Database migrations run with `npm run db:migrate`. Always run after schema changes.\n- The deploy script is `.claude/scripts/deploy.sh`. Requires VPN connection.\n\n## Tools & Scripts\n\n- Email checking: `.claude/scripts/check-email.py` — reads Gmail via API\n- Deployment: `.claude/scripts/deploy.sh` — wraps Vercel CLI with env injection\n\n## Lessons Learned\n\n- 2025-03-12: Never run `npm run build` during a deploy in production — it overwrites\n  the staging environment's assets. Use `npm run build:prod` instead.\n- 2025-03-15: Alex's preferred way to see reports is as a Telegram message, not a file.\n  Always relay summaries after writing reports.\n```\n\n`MEMORY.md` is the agent's persistent learning journal. Write to it when you discover something worth remembering. It's loaded at every session start.\n\n---\n\n## Identity Hooks (Automatic)\n\nInstar registers two Claude Code hooks that fire automatically.\n\n### Session Start Hook\n\n**File**: `.instar/hooks/instar/session-start.sh`\n\nFires at every session start (PostToolUse on the first tool call). Outputs a compact orientation:\n\n```\n=== ARIA — SESSION START ===\nIdentity: .instar/AGENT.md\nMemory:   .instar/MEMORY.md\nUser:     .instar/USER.md\nServer:   curl http://localhost:4040/health\n===========================\n```\n\nThis ensures the agent knows where its identity files are, even in sessions spawned by the scheduler.\n\n### Compaction Recovery Hook\n\n**File**: `.instar/hooks/compaction-recovery.sh`\n\nFires automatically after context compaction (the `compact` notification event). Outputs the full content of `AGENT.md` and `MEMORY.md` into the compressed context.\n\nThis is the critical one. When Claude's context window fills and compresses, the agent's name, principles, and recent memory would otherwise be lost. The hook re-injects them immediately after compression completes.\n\n---\n\n## Manual Orientation (When Hooks Don't Fire)\n\nIf you detect that identity has been lost — confusion about name, principles, or current task — orient manually:\n\n### Step 1: Read identity files\n\n```bash\ncat .instar/AGENT.md\ncat .instar/USER.md\ncat .instar/MEMORY.md\n```\n\n### Step 2: Check infrastructure state\n\n```bash\n# What's running\ncurl http://localhost:4040/status\n\n# What jobs exist\ncurl http://localhost:4040/jobs\n\n# What's happened recently\ncurl \"http://localhost:4040/events?since=4\" | python3 -m json.tool\n```\n\n### Step 3: Re-orient with compaction seed format\n\nAfter reading identity files, compose an internal orientation statement:\n\n```\nI am [AGENT_NAME]. Session goal: [what I was working on].\nCore files: .instar/AGENT.md (identity), .instar/MEMORY.md (learnings), .instar/USER.md (user context).\nServer: curl http://localhost:[PORT]/health\n```\n\n---\n\n## Updating Identity Over Time\n\nIdentity is not static. The agent should update its own identity files as it learns.\n\n### Writing to MEMORY.md\n\nWrite to `MEMORY.md` when you:\n- Discover a project pattern that will save time next session\n- Learn something important about the user's preferences\n- Make a mistake worth not repeating\n- Build a new script or capability\n\n```bash\n# Append a new memory entry\ncat >> .instar/MEMORY.md << 'EOF'\n\n## New Pattern (2025-03-20)\n\n- Deploy script now requires `--env production` flag since the March update.\n  Old invocation: `.claude/scripts/deploy.sh`\n  New invocation: `.claude/scripts/deploy.sh --env production`\nEOF\n```\n\n### Updating AGENT.md principles\n\nWhen the agent consistently acts in a way that diverges from its stated principles, update the principles to reflect the actual evolved behavior. Identity is earned through work, not declared once.\n\n### Updating USER.md\n\nWhen the user reveals new preferences, note them immediately:\n\n```bash\n# Example: user expressed preference during conversation\necho \"\\n- Prefers weekly summaries over daily status updates (expressed 2025-03-18)\" >> .instar/USER.md\n```\n\n---\n\n## Identity Across Spawned Sessions\n\nWhen the current session spawns a child session via the sessions API, the child inherits:\n\n- The project's `CLAUDE.md` (which references the identity files)\n- All identity hooks (they fire in every Claude Code session)\n- Access to `.instar/AGENT.md`, `USER.md`, and `MEMORY.md`\n\nChild sessions do not need to be separately grounded. The hooks handle it. However, for long-running or complex sub-agent tasks, including a brief orientation in the spawn prompt is good practice:\n\n```json\n{\n  \"name\": \"audit-task\",\n  \"prompt\": \"You are [AGENT_NAME], working on [PROJECT]. Your identity: .instar/AGENT.md. Your memory: .instar/MEMORY.md. Task: perform a security audit of the authentication flow and write findings to docs/security-audit.md.\"\n}\n```\n\n---\n\n## The Philosophy: Structure Over Willpower\n\nThe naive approach to agent identity is to tell the agent \"remember who you are.\" This fails because:\n\n1. Context compaction erases the instruction\n2. Long sessions accumulate context that buries the identity statement\n3. Spawned sessions start from zero\n\nInstar's approach: make forgetting structurally impossible. Hooks re-inject. Files persist. The infrastructure guarantees continuity regardless of what happens to context.\n\nAn agent with persistent identity makes better decisions, maintains consistent behavior across sessions, and builds genuine continuity with the people it works with. This is what separates an agent from a stateless function call.","tags":["instar","identity","jkheadley","agent-framework","agent-identity","agent-infrastructure","agent-memory","agent-skills","ai-agents","ai-safety","autonomous-agents","claude-code"],"capabilities":["skill","source-jkheadley","skill-instar-identity","topic-agent-framework","topic-agent-identity","topic-agent-infrastructure","topic-agent-memory","topic-agent-skills","topic-ai-agents","topic-ai-safety","topic-autonomous-agents","topic-claude-code","topic-cli","topic-cron","topic-job-scheduler"],"categories":["instar"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/JKHeadley/instar/instar-identity","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add JKHeadley/instar","source_repo":"https://github.com/JKHeadley/instar","install_from":"skills.sh"}},"qualityScore":"0.479","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 59 github stars · SKILL.md body (9,724 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-02T06:55:53.337Z","embedding":null,"createdAt":"2026-04-18T22:14:35.291Z","updatedAt":"2026-05-02T06:55:53.337Z","lastSeenAt":"2026-05-02T06:55:53.337Z","tsv":"'-03':738,764,1112,1197 '-12':739 '-15':765 '-18':1198 '-20':1113 '/dev/null':101,105 '/health':1042 '1':94,369,496,959,1335 '2':100,104,106,231,379,501,971,1341 '2025':737,763,1111,1196 '3':282,392,512,1001,1351 '4':294,401,522,996 '4040/events':994 '4040/health':293,855 '4040/jobs':987 '4040/status':981 '5':315,527 'access':1238 'accumul':403,1344 'acknowledg':274 'across':49,224,409,680,1201,1391 'act':1141 'actual':1157 'agent':8,22,47,56,125,173,182,205,241,336,375,406,413,441,453,566,586,646,658,670,790,859,913,1020,1052,1139,1266,1287,1321,1327,1381,1408 'agent.md':438,563,892,1135 'agre':262 'alex':539,590,613,640,766 'alongsid':465 'alreadi':665 'alway':705,781 'answer':543,599 'api':726,1215 'append':1101 'approach':1319,1359 'aria':444,450,674,843 'ask':477,493,556,660 'asset':756 'audit':1282,1302 'audit-task':1281 'authent':1305 'automat':190,813,822,879 'autonom':17,67,452 'avail':93 'bash':963,975,1100,1179 'becom':249,693 'behavior':1159,1390 'better':1386 'break':482 'brief':1270 'build':219,497,615,744,760,1094,1394 'buri':1347 'call':838,1413 'capabl':1099 'cat':964,966,968,1106 'chang':366,709 'check':89,95,721,972 'child':1210,1217,1244 'claud':118,329,817,905,1235 'claude.md':1222 'claude/scripts/check-email.py':722 'claude/scripts/deploy.sh':714,728,1127,1130 'cli':731 'code':119,330,818,1236 'collabor':467,537,593 'command':237 'communic':596 'compact':13,63,203,355,393,841,873,882,884,1006,1337 'compil':521 'complet':474,933 'complex':1263 'compos':1013 'compress':32,160,400,897,911,932 'confus':949 'connect':717 'consist':1140,1389 'content':890 'context':12,31,62,74,149,158,202,354,399,612,648,881,898,907,1037,1336,1345,1379 'continu':58,221,1373,1396 'convers':1185 'core':580,1029 'critic':902 'curl':290,853,979,985,992,1039 'current':954,1206 'daili':1192 'databas':697 'day':226 'db':703 'decis':1387 'declar':1166 'declin':273 'default':364 'defin':564 'deploy':711,727,747,1114 'describ':500 'detect':943 'develop':595 'direct':472,542,598 'discov':800,1070 'disk':378 'diverg':1146 'docs/security-audit.md':1311 'document':582 'doesn':126,131,136,206,414 'done':516 'earn':1162 'echo':1186 'email':720 'email/customer':629 'ensur':857 'entri':691,1105 'env':733,1118,1131 'environ':754 'eof':1108,1133 'eras':169,1338 'establish':4 'even':161,866 'event':886 'everi':117,150,195,246,328,389,808,830,1234 'evolv':1158 'exampl':1180 'exist':109,984 'explain':146 'explan':601 'express':1182,1195 'fail':1333 'fast':622 'file':178,371,427,430,634,678,780,826,864,876,962,1012,1030,1058,1227,1368 'fill':909 'find':1309 'fire':821,828,878,940,1232 'first':836 'flag':1120 'flow':1306 'follow':267 'forget':1361 'format':1008 'fragil':163 'full':889 'function':1412 'genuin':220,1395 'get':83,168 'give':55,171,644 'gmail':724 'goal':1023 'good':1277 'ground':1252 'grow':504 'guarante':216,424,1372 'handl':458,1255 'happen':990,1377 'histori':341 'honest':524 'hook':189,383,395,812,819,825,875,925,937,1230,1254,1364 'howev':1257 'human':651 'ident':3,9,40,45,48,53,69,177,193,324,360,370,387,397,426,429,581,811,846,863,945,961,1011,1032,1044,1047,1057,1160,1200,1226,1229,1293,1322,1349,1384 'immedi':930,1178 'import':1082 'imposs':1363 'improvis':530 'in-sess':164 'includ':1268 'inform':552 'infrastructur':41,79,215,423,528,973,1371 'inherit':1218 'inject':191,386,734,928,1367 'instal':113,286 'instar':2,44,51,91,97,103,110,170,239,265,284,301,312,327,365,433,814,1357 'instar-ident':1,43 'instar.sh':257,258,279 'instar/agent.md':847,965,1031,1240,1294 'instar/config.json':99 'instar/hooks/compaction-recovery.sh':877 'instar/hooks/instar/session-start.sh':827 'instar/memory.md':849,969,1033,1107,1297 'instar/user.md':851,967,1035,1199 'instead':762 'instruct':321,1340 'interact':269 'intern':1015 'investig':484 'invoc':1126,1129 'isn':70 'issu':630 'iter':623 'job':983 'journal':794 'json':1279 'json.tool':999 'know':25,128,252,666,860 'lead':594 'learn':141,254,353,408,510,637,672,686,736,793,1034,1061,1080 'lesson':735 'limit':526 'live':431 'load':806 'localhost':292,854,980,986,993,1040 'long':1260,1342 'long-run':1259 'lost':923,948 'ls':98 'm':998 'main':619 'maintain':1388 'make':1088,1360,1385 'manual':934,957 'march':1123 'markdown':443,589,673 'mean':517 'memori':167,676,848,919,1104,1296 'memory.md':402,507,667,787,894,1064,1067,1243 'menus':548 'messag':777 'mid':154,358 'mid-sess':153,357 'migrat':698,704 'minut':232 'mistak':1090 'monitor':461 'morn':247 'n':1187 'naiv':1318 'name':130,339,568,915,951,1021,1280,1288 'need':23,303,1248 'neither':108 'never':740 'new':1096,1103,1109,1128,1174 'next':561,1078 'note':631,1176 'notif':885 'npm':701,742,758 'npx':238,264 'obvious':560 'old':1125 'one':236,903 'oper':18,68 'option':547,605 'orient':33,842,935,956,1004,1016,1271 'otherwis':921 'outcom':515,545,603 'outdat':694 'output':839,887 'overwrit':751 'pattern':696,1073,1110 'peopl':1399 'perform':1299 'permiss':558,611 'persist':7,46,175,647,679,792,1369,1383 'person':468,570 'philosophi':1313 'port':1041 'posttoolus':833 'practic':1278 'precis':469 'prefer':135,541,597,602,642,768,1087,1175,1183,1188 'prevent':656 'primari':536,592 'principl':495,571,916,952,1136,1150,1153 'prioriti':620 'proactiv':470,606 'proceed':318 'prod':761 'product':618,749,1119,1132 'progress':554 'project':436,456,695,1072,1220,1291 'prompt':1275,1284 'python3':997 'question':479 're':145,385,927,1003,1366 're-explain':144 're-inject':384,926,1365 're-ori':1002 'read':723,960,1010 'readi':281 'recal':138 'recent':918,991 'recov':6,29 'recoveri':394,874 'refer':1224 'reflect':1155 'regardless':1374 'regist':815 'relationship':573 'relay':782 'reliabl':621 'rememb':133,210,418,502,689,803,1328 'remov':690 'repeat':1093 'report':486,772,786 'request':609 'requir':715,1117 'restart':15,65 'restor':199,396 'reveal':1173 'role':569 'root':437 'run':263,299,306,317,518,699,702,706,741,743,759,978,1261 'saa':617 'save':1076 'schedul':459,872 'schema':708 'script':712,719,1097,1115 'secur':1301 'see':771 'seed':1007 'self':59,176 'sens':343 'separ':1251,1406 'server':289,296,302,313,852,1038 'session':14,35,50,64,120,155,166,196,225,331,359,381,390,411,681,809,823,831,844,868,1022,1079,1203,1207,1211,1214,1237,1245,1343,1353,1392 'session-start':380 'set':234 'setup':270 'sf':291 'sinc':995,1121 'skill':88 'skill-instar-identity' 'someon':250 'someth':481,511,687,801,1081 'source-jkheadley' 'spawn':869,1202,1208,1274,1352 'stage':753 'start':36,84,121,197,310,314,332,382,391,810,824,832,845,1354 'state':974,1149 'stateless':1411 'statement':1017,1350 'static':1050 'status':1193 'stay':625 'step':562,958,970,1000 'stop':242 'store':72,77,179,372 'stranger':245 'structur':80,368,1314,1362 'sub':1265 'sub-ag':1264 'suggest':276 'summari':783,1190 'surviv':11,61 'system':54,462 'take':229 'task':460,955,1267,1283,1298 'telegram':776 'tell':114,1325 'thing':662 'time':151,1046,1077 'tool':718,837 'top':627 'topic-agent-framework' 'topic-agent-identity' 'topic-agent-infrastructure' 'topic-agent-memory' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-safety' 'topic-autonomous-agents' 'topic-claude-code' 'topic-cli' 'topic-cron' 'topic-job-scheduler' 'tri':208,416 'trigger':42 'two':816 'understand':38 'unnecessari':478 'updat':607,632,1043,1054,1124,1134,1151,1168,1194 'use':19,86,757 'user':116,261,576,850,1036,1085,1172,1181 'user.md':583,643,1169,1241 'valu':550 'vercel':730 'verifi':287 'via':725,1212 'visit':278 'vpn':716 'wait':490 'want':307 'way':769,1144 'week':227,1189 'willpow':82,1316 'window':159,908 'wipe':356 'without':326,476 'work':187,325,347,464,475,533,587,653,1027,1164,1289,1401 'worth':688,802,1091 'would':920 'wrap':729 'write':505,682,785,795,1062,1065,1308 'yesterday':142 'zero':123,334,1356","prices":[{"id":"ab79eb7f-0dd6-4ab5-8e1b-85d958eeafdd","listingId":"6c2d9654-edb0-4d3a-9a12-cdb11ab83a9f","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"JKHeadley","category":"instar","install_from":"skills.sh"},"createdAt":"2026-04-18T22:14:35.291Z"}],"sources":[{"listingId":"6c2d9654-edb0-4d3a-9a12-cdb11ab83a9f","source":"github","sourceId":"JKHeadley/instar/instar-identity","sourceUrl":"https://github.com/JKHeadley/instar/tree/main/skills/instar-identity","isPrimary":false,"firstSeenAt":"2026-04-18T22:14:35.291Z","lastSeenAt":"2026-05-02T06:55:53.337Z"}],"details":{"listingId":"6c2d9654-edb0-4d3a-9a12-cdb11ab83a9f","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"JKHeadley","slug":"instar-identity","github":{"repo":"JKHeadley/instar","stars":59,"topics":["agent-framework","agent-identity","agent-infrastructure","agent-memory","agent-skills","ai-agents","ai-safety","autonomous-agents","claude-code","cli","cron","job-scheduler","llm","mcp","npm-package","open-source","persistency","telegram-bot","typescript","whatsapp"],"license":"mit","html_url":"https://github.com/JKHeadley/instar","pushed_at":"2026-05-02T05:23:59Z","description":"Persistent Claude Code agents with scheduling, sessions, memory, and Telegram.","skill_md_sha":"505fedfba1e129d1e413410f0fec69329a5ddc42","skill_md_path":"skills/instar-identity/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/JKHeadley/instar/tree/main/skills/instar-identity"},"layout":"multi","source":"github","category":"instar","frontmatter":{"name":"instar-identity","license":"MIT","description":"Establish and recover persistent agent identity that survives context compaction, session restarts, and autonomous operation. Use when an agent needs to know who it is, recover after context compression, orient at session start, or understand the identity infrastructure. Trigger words: who am I, remember, identity, after restart, compaction, context loss, who am I working with, my principles.","compatibility":"Works best with instar (npx instar). If not installed, the skill will guide you through setup."},"skills_sh_url":"https://skills.sh/JKHeadley/instar/instar-identity"},"updatedAt":"2026-05-02T06:55:53.337Z"}}