{"id":"f9ceafdb-9175-4793-989a-933743096398","shortId":"JFjFuq","kind":"skill","title":"instar-scheduler","tagline":"Schedule recurring agent tasks using cron expressions. Use when the user asks to run something on a schedule, check something periodically, automate a recurring task, set up a cron job, or wants work to happen while they're away. Trigger words: schedule, recurring, cron, every ho","description":"# instar-scheduler — Schedule Recurring Agent Tasks\n\nInstar's job scheduler lets you define tasks that run automatically on a cron schedule. Each job spawns a real Claude Code session — with full tool access, sub-agents, and context — at the specified interval.\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   > \"Right now, your agent only works when you're sitting at your computer. You close the laptop, it stops. Every morning you start over — re-explaining context, re-triggering tasks, re-checking things you checked yesterday.\n   >\n   > **Instar gives your agent a heartbeat.** Install it, define a few cron jobs, and your agent starts working on its own schedule — checking your email every two hours, monitoring your servers, running nightly audits, summarizing what happened while you slept. You wake up to a report of everything it handled overnight.\n   >\n   > It takes about 2 minutes to set up. One command:\n   >\n   > ```\n   > npx instar\n   > ```\n   >\n   > Your agent goes from a tool you use to a teammate that works alongside 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## Job Format\n\nJobs are defined in `.instar/jobs.json` as a JSON array. Each job object has these fields:\n\n```json\n{\n  \"slug\": \"check-emails\",\n  \"name\": \"Email Check\",\n  \"description\": \"Check for new emails and summarize anything urgent\",\n  \"schedule\": \"0 */2 * * *\",\n  \"priority\": \"high\",\n  \"model\": \"sonnet\",\n  \"enabled\": true,\n  \"execute\": {\n    \"type\": \"prompt\",\n    \"value\": \"Check email for new messages. Summarize anything urgent and send to Telegram.\"\n  }\n}\n```\n\n### Field Reference\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `slug` | Yes | Unique identifier. Lowercase, hyphens only. |\n| `name` | Yes | Human-readable name shown in dashboards and Telegram |\n| `description` | No | What this job does (shown in status, helps with context) |\n| `schedule` | Yes | Cron expression (see below) |\n| `priority` | No | `critical`, `high`, `normal`, `low` (default: `normal`) |\n| `model` | No | `opus`, `sonnet`, `haiku` (default: `sonnet`) |\n| `enabled` | No | `true` or `false` (default: `true`) |\n| `execute.type` | Yes | `prompt`, `script`, or `skill` |\n| `execute.value` | Yes | The prompt text, script path, or skill name |\n\n---\n\n## Cron Schedule Syntax\n\nStandard 5-field cron: `minute hour day-of-month month day-of-week`\n\n```\n┌───────────── minute (0-59)\n│ ┌───────────── hour (0-23)\n│ │ ┌───────────── day of month (1-31)\n│ │ │ ┌───────────── month (1-12)\n│ │ │ │ ┌───────────── day of week (0-6, 0=Sunday)\n│ │ │ │ │\n* * * * *\n```\n\n### Common Patterns\n\n| Schedule | Cron expression |\n|----------|----------------|\n| Every 5 minutes | `*/5 * * * *` |\n| Every hour | `0 * * * *` |\n| Every 2 hours | `0 */2 * * *` |\n| Daily at midnight | `0 0 * * *` |\n| Daily at 9 AM | `0 9 * * *` |\n| Weekdays at 8 AM | `0 8 * * 1-5` |\n| Weekly (Monday 9 AM) | `0 9 * * 1` |\n| Every 30 minutes | `*/30 * * * *` |\n\n---\n\n## Priority and Model Tiers\n\n**Priority** controls execution order when multiple jobs are queued simultaneously:\n\n- `critical` — Runs first, never skipped during quota constraints\n- `high` — Runs before normal jobs; use for user-facing or time-sensitive work\n- `normal` — Default; standard scheduling\n- `low` — Runs last; use for maintenance tasks that can wait\n\n**Model** controls which Claude model runs the session:\n\n- `opus` — Complex reasoning, high-stakes decisions, creative synthesis\n- `sonnet` — Default; balanced capability and cost; most jobs should use this\n- `haiku` — Routine checks, simple reads, health monitoring; lowest cost\n\nInstar is quota-aware. During periods of heavy usage, low-priority jobs may be deferred. Critical jobs are never skipped.\n\n---\n\n## Execute Types\n\n### `prompt` — Run a Claude session with this instruction\n\n```json\n{\n  \"execute\": {\n    \"type\": \"prompt\",\n    \"value\": \"Check the server health endpoints. If anything is degraded, send a Telegram alert.\"\n  }\n}\n```\n\n### `script` — Run a shell script directly (no Claude session)\n\n```json\n{\n  \"execute\": {\n    \"type\": \"script\",\n    \"value\": \".claude/scripts/backup-database.sh\"\n  }\n}\n```\n\n### `skill` — Invoke a slash skill\n\n```json\n{\n  \"execute\": {\n    \"type\": \"skill\",\n    \"value\": \"reflect\"\n  }\n}\n```\n\n---\n\n## Adding a Job\n\n### Option 1: CLI (recommended for simple jobs)\n\n```bash\ninstar job add \\\n  --slug check-email \\\n  --name \"Email Check\" \\\n  --schedule \"0 */2 * * *\" \\\n  --description \"Check for urgent emails and relay to Telegram\" \\\n  --priority high \\\n  --model sonnet\n```\n\n### Option 2: Edit jobs.json directly\n\nOpen `.instar/jobs.json` and add a job object to the array. The scheduler reloads jobs automatically within 60 seconds, or trigger a reload:\n\n```bash\ncurl -X POST http://localhost:4040/jobs/reload\n```\n\n### Option 3: The agent adds its own jobs\n\nWhen a user says \"check my emails every two hours,\" the correct agent behavior is to write the job directly to `.instar/jobs.json` and confirm it's active — not ask for permission.\n\n---\n\n## Managing Jobs\n\n### View all jobs and their next run times\n\n```bash\ncurl http://localhost:4040/jobs | python3 -m json.tool\n```\n\n### Trigger a job manually (test it now)\n\n```bash\ncurl -X POST http://localhost:4040/jobs/check-email/trigger\n```\n\n### Disable a job without deleting it\n\nSet `\"enabled\": false` in the job definition, or:\n\n```bash\ninstar job disable check-email\n```\n\n### View recent execution history\n\n```bash\ncurl \"http://localhost:4040/events?type=job_completed&since=24\" | python3 -m json.tool\n```\n\n---\n\n## Telegram Integration\n\nEach job automatically gets its own Telegram topic when Telegram is configured. Job execution results are posted to that topic, creating a living dashboard of what your agent is doing.\n\n- The topic name matches the job's `name` field\n- Completion summaries include duration, status, and a brief summary\n- Failed jobs post error context so you can diagnose without checking logs\n\n---\n\n## Default Jobs (Ships with Instar)\n\nInstar includes these coherence jobs out of the box:\n\n| Slug | Schedule | Model | Purpose |\n|------|----------|-------|---------|\n| `health-check` | Every 5 min | Haiku | Verify infrastructure health |\n| `reflection-trigger` | Every 4h | Sonnet | Reflect on recent work, update MEMORY.md |\n| `relationship-maintenance` | Daily | Sonnet | Surface stale relationships |\n| `update-check` | Daily | Haiku | Detect new Instar versions |\n| `feedback-retry` | Every 6h | Haiku | Retry failed feedback forwards |\n\nYou can modify or disable any of these by editing `.instar/jobs.json`.\n\n---\n\n## Self-Evolution Pattern\n\nAgents using Instar are expected to create and modify their own jobs. When the user asks for a new recurring capability, the agent should:\n\n1. Check if a suitable job already exists: `curl http://localhost:4040/jobs`\n2. Write the job definition to `.instar/jobs.json`\n3. Trigger a test run: `curl -X POST http://localhost:4040/jobs/SLUG/trigger`\n4. Confirm the result to the user\n\nThe agent doesn't ask permission before adding jobs. Scheduling work is continuation, not a decision point.","tags":["instar","scheduler","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-scheduler","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-scheduler","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 (7,642 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.434Z","embedding":null,"createdAt":"2026-04-18T22:14:36.073Z","updatedAt":"2026-05-02T06:55:53.434Z","lastSeenAt":"2026-05-02T06:55:53.434Z","tsv":"'-12':482 '-23':474 '-31':479 '-5':525 '-59':471 '-6':487 '/2':349,506,724 '/30':536 '/5':498 '/dev/null':111,115 '0':348,470,473,486,488,501,505,510,511,516,522,530,723 '1':104,478,481,524,532,705,1045 '2':110,114,116,220,503,739,1056 '24':873 '3':272,772,1063 '30':534 '4':284,1073 '4040/events':868 '4040/health':283 '4040/jobs':823,1055 '4040/jobs/check-email/trigger':839 '4040/jobs/reload':770 '4040/jobs/slug/trigger':1072 '4h':971 '5':305,455,496,961 '60':759 '6h':1000 '8':520,523 '9':514,517,528,531 'access':83 'acknowledg':264 'activ':805 'ad':701,1087 'add':714,746,775 'agent':6,55,86,130,169,181,230,774,791,906,1021,1043,1081 'agre':252 'alert':674 'alongsid':242 'alreadi':1051 'anyth':345,366,668 'array':323,752 'ask':15,807,1036,1084 'audit':199 'autom':25 'automat':67,757,881 'avail':103 'awar':629 'away':42 'balanc':607 'bash':711,765,820,834,854,865 'behavior':792 'box':952 'brief':925 'capabl':608,1041 'check':22,99,105,161,164,188,333,337,339,360,618,662,717,721,726,783,859,937,959,989,1046 'check-email':332,716,858 'claud':77,591,652,682 'claude/scripts/backup-database.sh':689 'cli':706 'close':141 'code':78 'coher':947 'command':226 'common':490 'complet':871,918 'complex':597 'comput':139 'configur':890 'confirm':802,1074 'constraint':558 'context':88,154,406,931 'continu':1092 'control':542,589 'correct':790 'cost':610,624 'creat':899,1027 'creativ':603 'critic':415,551,642 'cron':9,32,47,70,177,409,451,457,493 'curl':280,766,821,835,866,1053,1068 'daili':507,512,982,990 'dashboard':392,902 'day':461,466,475,483 'day-of-month':460 'day-of-week':465 'decis':602,1095 'declin':263 'default':419,426,433,575,606,939 'defer':641 'defin':63,174,317 'definit':852,1060 'degrad':670 'delet':844 'descript':338,376,395,725 'detect':992 'diagnos':935 'direct':680,742,798 'disabl':840,857,1010 'doesn':1082 'durat':921 'edit':740,1015 'email':190,334,336,342,361,718,720,729,785,860 'enabl':354,428,847 'endpoint':666 'error':930 'everi':48,146,191,495,499,502,533,786,960,970,999 'everyth':213 'evolut':1019 'execut':356,543,647,658,685,696,863,892 'execute.type':435 'execute.value':441 'exist':119,1052 'expect':1025 'explain':153 'express':10,410,494 'face':568 'fail':927,1003 'fals':432,848 'feedback':997,1004 'feedback-retri':996 'field':329,372,374,456,917 'first':553 'follow':257 'format':314 'forward':1005 'full':81 'get':93,882 'give':167 'goe':231 'haiku':425,616,963,991,1001 'handl':215 'happen':38,202 'health':621,665,958,966 'health-check':957 'heartbeat':171 'heavi':633 'help':404 'high':351,416,559,600,735 'high-stak':599 'histori':864 'ho':49 'hour':193,459,472,500,504,788 'human':387 'human-read':386 'hyphen':382 'identifi':380 'includ':920,945 'infrastructur':965 'instal':123,172,276 'instar':2,51,57,101,107,113,120,166,228,255,274,291,302,625,712,855,943,944,994,1023 'instar-schedul':1,50 'instar.sh':247,248,269 'instar/config.json':109 'instar/jobs.json':319,744,800,1016,1062 'instruct':311,656 'integr':878 'interact':259 'interv':92 'invok':691 'job':33,59,73,178,313,315,325,399,547,563,612,638,643,703,710,713,748,756,778,797,811,814,829,842,851,856,870,880,891,914,928,940,948,1032,1050,1059,1088 'jobs.json':741 'json':322,330,657,684,695 'json.tool':826,876 'laptop':143 'last':580 'learn':244 'let':61 'live':901 'localhost':282,769,822,838,867,1054,1071 'log':938 'low':418,578,636 'low-prior':635 'lowercas':381 'lowest':623 'ls':108 'm':825,875 'mainten':583,981 'manag':810 'manual':830 'match':912 'may':639 'memory.md':978 'messag':364 'midnight':509 'min':962 'minut':221,458,469,497,535 'model':352,421,539,588,592,736,955 'modifi':1008,1029 'monday':527 'monitor':194,622 'month':463,464,477,480 'morn':147 'multipl':546 'name':335,384,389,450,719,911,916 'need':293 'neither':118 'never':554,645 'new':341,363,993,1039 'next':817 'night':198 'normal':417,420,562,574 'npx':227,254 'object':326,749 'one':225 'open':743 'option':704,738,771 'opus':423,596 'order':544 'overnight':216 'path':447 'pattern':491,1020 'period':24,631 'permiss':809,1085 'point':1096 'post':768,837,895,929,1070 'prioriti':350,413,537,541,637,734 'proceed':308 'prompt':358,437,444,649,660 'purpos':956 'python3':824,874 'queu':549 'quota':557,628 'quota-awar':627 're':41,135,152,156,160 're-check':159 're-explain':151 're-trigg':155 'read':620 'readabl':388 'readi':271 'real':76 'reason':598 'recent':862,975 'recommend':707 'recur':5,27,46,54,1040 'refer':373 'reflect':700,968,973 'reflection-trigg':967 'relationship':980,986 'relationship-mainten':979 'relay':731 'reload':755,764 'report':211 'requir':375 'result':893,1076 'retri':998,1002 'right':127 'routin':617 'run':17,66,197,253,289,296,307,552,560,579,593,650,676,818,1067 'say':782 'schedul':3,4,21,45,52,53,60,71,187,347,407,452,492,577,722,754,954,1089 'script':438,446,675,679,687 'second':760 'see':411 'self':1018 'self-evolut':1017 'send':369,671 'sensit':572 'server':196,279,286,292,303,664 'session':79,595,653,683 'set':29,223,846 'setup':260 'sf':281 'shell':678 'ship':941 'shown':390,401 'simpl':619,709 'simultan':550 'sinc':872 'sit':136 'skill':98,440,449,690,694,698 'skill-instar-scheduler' 'skip':555,646 'slash':693 'slept':205 'slug':331,377,715,953 'someth':18,23 'sonnet':353,424,427,605,737,972,983 'source-jkheadley' 'spawn':74 'specifi':91 'stake':601 'stale':985 'standard':454,576 'start':94,149,182,300,304 'status':403,922 'stop':145 'sub':85 'sub-ag':84 'suggest':266 'suitabl':1049 'summar':200,344,365 'summari':919,926 'sunday':489 'surfac':984 'syntax':453 'synthesi':604 'take':218 'task':7,28,56,64,158,584 'teammat':239 'telegram':371,394,673,733,877,885,888 'tell':124 'test':831,1066 'text':445 'thing':162 'tier':540 'time':571,819 'time-sensit':570 'tool':82,234 'topic':886,898,910 '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' 'trigger':43,157,762,827,969,1064 'true':355,430,434 'two':192,787 'type':357,648,659,686,697,869 'uniqu':379 'updat':977,988 'update-check':987 'urgent':346,367,728 'usag':634 'use':8,11,96,236,564,581,614,1022 'user':14,126,251,567,781,1035,1079 'user-fac':566 'valu':359,661,688,699 'verifi':277,964 'version':995 'view':812,861 'visit':268 'wait':587 'wake':207 'want':35,297 'week':468,485,526 'weekday':518 'within':758 'without':843,936 'word':44 'work':36,132,183,241,573,976,1090 'write':795,1057 'x':767,836,1069 'yes':378,385,408,436,442 'yesterday':165","prices":[{"id":"c6534d00-e4b0-43d4-a0e0-c6816d88f23e","listingId":"f9ceafdb-9175-4793-989a-933743096398","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:36.073Z"}],"sources":[{"listingId":"f9ceafdb-9175-4793-989a-933743096398","source":"github","sourceId":"JKHeadley/instar/instar-scheduler","sourceUrl":"https://github.com/JKHeadley/instar/tree/main/skills/instar-scheduler","isPrimary":false,"firstSeenAt":"2026-04-18T22:14:36.073Z","lastSeenAt":"2026-05-02T06:55:53.434Z"}],"details":{"listingId":"f9ceafdb-9175-4793-989a-933743096398","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"JKHeadley","slug":"instar-scheduler","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":"7f43e790b4cc88195bb06e7b7493493fb1c3552c","skill_md_path":"skills/instar-scheduler/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/JKHeadley/instar/tree/main/skills/instar-scheduler"},"layout":"multi","source":"github","category":"instar","frontmatter":{"name":"instar-scheduler","license":"MIT","description":"Schedule recurring agent tasks using cron expressions. Use when the user asks to run something on a schedule, check something periodically, automate a recurring task, set up a cron job, or wants work to happen while they're away. Trigger words: schedule, recurring, cron, every hour, every day, run daily, periodic, automated.","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-scheduler"},"updatedAt":"2026-05-02T06:55:53.434Z"}}