schedule · orwa-mahmoud — Claude Code skill: scheduled shift setup
A Claude Code skill that prints scheduler configuration for starting a shift at a set time. It checks the Nightshift workspace and queued work before generating it.
MIT ★ 571 updated 2026-11-16
npx skills add orwa-mahmoud/nightshift --skill schedule -a claude-codeWhat schedule does
The skill checks the Nightshift workspace, punch list and agent permissions, then prints configuration for a timed shift start. Enter the time in local HH:MM format. Codex generation also takes the agent launch command.
A configured Nightshift workspace and items in $NS/punch-list.md are needed; an empty list leaves the scheduled run with nothing to do. The skill does not install or register a job. The owner runs the printed command, and the shift log goes to $NS/run/scheduled.log.
What it helps with
- print scheduler configuration for a shift
- check queued tasks before setting a run time
- flag missing permissions for a headless start
- show registered jobs or the command to remove one
Example prompts for the agent
- Set up a Nightshift shift to start at 22:30 local time.
- Check the workspace and print the configuration for a 06:15 start.
- Show the registered Nightshift job and its removal command.
How to install schedule
1Skills CLI (Vercel)
npx skills add orwa-mahmoud/nightshift --skill schedule -a claude-code2Manually: put the files in place
~/.claude/skills/schedule/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/schedule/
1Skills CLI (Vercel)
npx skills add orwa-mahmoud/nightshift --skill schedule -a codex2Manually: put the files in place
.agents/skills/schedule/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add orwa-mahmoud/nightshift --skill schedule -a cursor2Manually: put the files in place
.cursor/skills/schedule/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install orwa-mahmoud/nightshift plugins/nightshift/skills/schedule2Manually: put the files in place
.github/skills/schedule/SKILL.md1Skills CLI (Vercel)
npx skills add orwa-mahmoud/nightshift --skill schedule -a gemini-cli2Platform CLI
gemini skills install https://github.com/orwa-mahmoud/nightshift --path plugins/nightshift/skills/scheduleManually: put the files in place
.devin/skills/schedule/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add orwa-mahmoud/nightshift --skill schedule -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about schedule
How do I install schedule in Claude Code?
Run npx skills add orwa-mahmoud/nightshift --skill schedule -a claude-code. The skill file is placed at ~/.claude/skills/schedule/SKILL.md.
What does schedule do?
It checks the Nightshift workspace, queued work and agent permissions, then prints scheduler configuration for a shift at a chosen time. It does not register the job.
Does schedule register the job automatically?
No. The owner runs the command printed by the generator; the skill does not install or register anything.
Source text
SKILL.md · MIT
---
name: schedule
description: Print the launchd, cron or Task Scheduler config that starts a shift at a fixed time; registers nothing.
license: MIT
metadata:
internal: true
---
Get the host-opened project ready to start on a clock, then hand the owner the config. Work through
these in order; each one is a check the owner would otherwise discover at 4am.
Resolve the installed plugin root to an absolute `$NIGHTSHIFT_PLUGIN_ROOT` — `${CLAUDE_PLUGIN_ROOT}`
on Claude Code, `$PLUGIN_ROOT` on Codex when set, otherwise the absolute path this skill was
attached from (`skills/schedule/SKILL.md`). Run every command below through
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns"` — native Windows: `& "$NIGHTSHIFT_PLUGIN_ROOT\runtime\windows\ns.ps1"`
in the PowerShell tool, same verbs — which resolves the host and the workspace; `ns help` lists the
verbs, and `ns bind` prints the six resolved facts (`TASK_ROOT`, `NIGHTSHIFT_WORKSPACE`, `NS`,
`NIGHTSHIFT_PLUGIN_ROOT`, `HOST`, `SOURCE`); `$NS` below is that `NS`. Never a bare relative path: the working
directory persists between calls. Each `$NS/...` path below is where the current layout keeps that file;
`ns path <key>` prints where this workspace keeps it, and `ns path --list` names every key.
## 1. Is there a site at all?
No `$NS/` — stop and point at Setup (`/nightshift:setup` on Claude Code, or ask Nightshift
to set up on Codex). Nothing below is meaningful without it.
Read `$NS/run/work-mode`. Artifact mode is a persistent folder, not a Git repository; the scheduled
agent still starts in that work target. A malformed mode or a scratch work target is a refuse —
fix it with Setup before installing a job. In artifact mode, refuse to print or install a job when `$NS/receipts` exists but is not a usable directory.
If `$NS/run/work-mode` is missing and Setup would propose artifact, refuse to print or install a job; a scheduled start will refuse to arm.
If the work target cannot be resolved, refuse to print or install a job; a scheduled start will refuse to arm.
## 2. Is there work queued?
A scheduled start works the punch list it finds and **promotes nothing** — parked work orders and
drafting-table entries stay exactly where they are. So an empty `## Items` means the scheduled run
does nothing at all, and this is the moment to fix that, not 4am.
Count the open `- [ ]` in `$NS/punch-list.md`:
- **Items present** — say what they are in one line and carry on.
- **None** — say so plainly and offer the ways to fix it: compose a shift now with
Hunt (answer **later**, not **now** — a shift started here defeats scheduling it), cut an
ordinary draft from `$NS/staging/drafting-table.md`, cut a `Status: proposed` import with
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" import-issues --promote …`, or write an
item by hand. Then re-check. Never schedule an empty list without saying it will do nothing.
A parked work order is not queued work. If one exists, say so: it must be moved into the punch list
before the scheduled time, because start will not promote it.
## 3. Will the permissions hold?
A scheduled run is headless and cannot answer a prompt. On Claude Code, if neither
`$TASK_ROOT/.claude/settings.local.json` nor `$TASK_ROOT/.claude/settings.json` grants
frictionless permissions, warn
once. On Codex the grant travels in the command itself: pass the owner's Codex launch command, as
the Codex host page (`$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/hosts/codex.md`)
spells it, through `--agent`. The generator's preflight warns when a Codex command carries no
headless grant, and a Codex entry generated without one will stall on the first tool that asks.
Setup offers the fix.
## 4. Confirm the queued work is unarmed
Open `- [ ]` Items do not activate the clock-out gate by themselves. `.shift-armed` does, and
scheduling must not create it: the work stays queued until the scheduled Start preflight clears
stale markers and arms the shift.
If `$NS/run/.shift-armed` already exists, stop here. This workspace has an active or stale shift,
not merely queued work. Report that state and point the owner to Status (`/nightshift:status` on
Claude Code, or ask Nightshift for status on Codex); do not tell them to create a STOP marker just
to schedule the list. Continue only after the existing shift has been ended or its stale state has
been diagnosed.
## 5. Print the config
Ask for the time if the owner has not given one — 24-hour `HH:MM`, local — then run the generator
and show its output as it comes:
```bash
"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" schedule --preflight
"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" schedule --at <HH:MM>
# Codex projects add: --agent '<the Codex launch command from references/hosts/codex.md>'
# Linux user timers: --target systemd
```
`--preflight` / `-Preflight` checks the agent binary, permissions, resolved workspace, rules, queued work,
generated paths, and scheduler syntax for Claude Code and Codex. It installs nothing, writes
nothing under LaunchAgents, and does not enable, start, or register an entry. `--list` shows what
is already registered for this project; `--remove` prints the command that unregisters it. The
generator refuses to hand over a second entry where one exists — two scheduled starts on one punch
list is two agents on one shift.
**Install nothing.** The owner runs the command it prints, or does not.
## 6. Close
Say where the run's output will land (`$NS/run/scheduled.log`), and
mention once that the same generator runs from a terminal with no session —
`ns schedule` is plain shell and spends no model tokens, which is
what makes it reachable on a day this command is not. On native Windows the equivalent is
; it likewise spends no model tokens and
registers nothing. The README carries the full offline note.
© orwa-mahmoud · MIT · orwa-mahmoud/nightshift
Similar skills
All skills for Agent setup: memory, context, orchestration →schedule by other authors comes first.