{
  "markdown": "# session-skills\n\nEight skills for the boundaries of a coding session — resume a turn that died,\naudit or hand off a session that is ending, carry an unattended run across a\ntoken-limit reset, defer a command by N minutes, and create or remove the\nisolated git worktree the work happens in. Packaged as a single plugin named\n`session`, installable on six coding-agent harnesses.\n\nThey are grouped by *when* they fire rather than by what they touch. That is the\nwhole organising idea: `restart` and `handoff` have nothing in common\ntechnically, but you reach for one or the other at the same moment — the session\nis in trouble and you have to decide whether to resume or write it down.\n\nUnlike its sibling [`harness-skills`](https://github.com/dEitY719/harness-skills),\nthis repo owns no shared assets — it links out for the\n[per-harness tool mappings and the CI workflow](#shared-assets).\n\n## Skills\n\n| Skill | Invoke | What it does |\n|-------|--------|--------------|\n| `restart` | `/session:restart` | Resumes a turn that died to an API error, an OOM, an auth expiry, or an ESC — same session, no cron. Picks the resume target off the TodoList, corroborates it against `git status`, then works in single-tool-call chunks with big reads delegated to subagents. |\n| `close` | `/session:close [--repos <path,...>]` | Audits four categories of leftover work across every repo the session touched and prints `[OK]` or `[BLOCKED]` plus one `Next:` line. **Strictly read-only** — it never changes a file, a git state, or a remote, and never runs `/exit` for you. |\n| `handoff` | `/session:handoff [issue] [remote] [--memory-only] [--new-issue]` | Writes *unfinished* work into a tracking-issue comment and an agent-local memory file, then prints a copy-paste resume sentence. Exactly two writes; nothing is committed or pushed. |\n| `rate-limit-guard` | `/session:rate-limit-guard --reset HH:MM [--max-cycles N] [--cycle-window M] <command>` | **[Claude Code only]** Arms a durable one-shot cron for `reset + 5min`, persists `.claude/.rate-limit-guard.json`, runs the wrapped command, and tears the safety net down on success. |\n| `resume-after-limit` | `/session:resume-after-limit [<command>]` | **[Claude Code only]** What that cron invokes. Reads the state file, stops hard on a worktree mismatch, pre-arms the next cycle, re-runs the wrapped command, cleans up on success. |\n| `schedule` | `/session:schedule [--time M] \"<command>\"` | **[Claude Code only]** Generic session-local deferral: run any slash command or task in M minutes (default 5). One-shot; the built-in `/loop` is for recurring interval runs. |\n| `worktree-spawn` | `/session:worktree-spawn [--ai <name>] [--task <slug>] [--base <ref>] [<branch>]` | Creates `../<project>-<agent>-<N>` on a `wt/<agent>/<N>` branch so parallel agents do not collide. Detects the agent, picks the next free index, resolves the base ref, and handles `git-crypt` repos. |\n| `worktree-teardown` | `/session:worktree-teardown <worktree-path> [--force] [--keep-branch] [--dry-run]` | Removes the worktree, syncs main, deletes the branch. **The destructive one** — blocks on uncommitted or unpushed work unless you pass `--force`. |\n\n### Visual guides and worked examples (GitHub Pages)\n\n- `restart` — [visual guide](https://deity719.github.io/session-skills/skill-guides/restart.html) · [usage example](https://deity719.github.io/session-skills/skill-output/restart-usage.html) (dead turn to resumed work in the same session)\n- `close` — [visual guide](https://deity719.github.io/session-skills/skill-guides/close.html) · [usage example](https://deity719.github.io/session-skills/skill-output/close-usage.html) (session state to an OK/BLOCKED verdict)\n- `handoff` — [visual guide](https://deity719.github.io/session-skills/skill-guides/handoff.html) · [usage example](https://deity719.github.io/session-skills/skill-output/handoff-usage.html) (unfinished work to an issue comment and a resume sentence)\n- `rate-limit-guard` — [visual guide](https://deity719.github.io/session-skills/skill-guides/rate-limit-guard.html) · [usage example](https://deity719.github.io/session-skills/skill-output/rate-limit-guard-usage.html) (a reset time to a durable cron and a state file)\n- `resume-after-limit` — [visual guide](https://deity719.github.io/session-skills/skill-guides/resume-after-limit.html) · [usage example](https://deity719.github.io/session-skills/skill-output/resume-after-limit-usage.html) (that state file to the re-run command)\n- `schedule` — [visual guide](https://deity719.github.io/session-skills/skill-guides/schedule.html) · [usage example](https://deity719.github.io/session-skills/skill-output/schedule-usage.html) (a command plus a delay to a one-shot cron)\n- `worktree-spawn` — [visual guide](https://deity719.github.io/session-skills/skill-guides/worktree-spawn.html) · [usage example](https://deity719.github.io/session-skills/skill-output/worktree-spawn-usage.html) (a main repo to an isolated worktree and branch)\n- `worktree-teardown` — [visual guide](https://deity719.github.io/session-skills/skill-guides/worktree-teardown.html) · [usage example](https://deity719.github.io/session-skills/skill-output/worktree-teardown-usage.html) (a worktree path to a removed worktree and a synced main)\n\nEach page is generated from a Markdown source under\n[`docs/skill-guides/`](docs/skill-guides) and [`docs/skill-output/`](docs/skill-output).\n\n### Two pairs worth knowing\n\n`rate-limit-guard` and `resume-after-limit` are one mechanism split across two\nfires. The guard computes `reset + 5min`, arms the cron, and writes the state\nfile; the resumer is what that cron calls — it verifies it woke up in the right\nworktree and re-runs the wrapped command, pre-arming the next cycle first when\n`--max-cycles > 1`. Neither is useful alone, which is why they ship together.\n\n`close` and `handoff` sit at the same moment and answer different questions.\nClose means the session finished cleanly: audit, verdict, no writes. Handoff\nmeans the session is running out of context with work unfinished: write that\nwork into a tracking issue so the next session starts from one sentence instead\nof an archaeology exercise. When `close` returns `[BLOCKED]` on unfinished work,\nits `Next:` line points at `handoff`.\n\n## Requirements\n\n| Skill | Needs |\n|-------|-------|\n| `restart` | Claude Code's `TaskList` / `TaskUpdate` (the session TodoList) and a subagent dispatch tool. Degrades elsewhere — see [Harness support](#harness-support). |\n| `close` | `bash` for its two `lib/` scripts; `git` in each audited repo; optionally `gh` for the C-4 issue/PR status check and `TaskList` for C-2. |\n| `handoff` | `gh`, authenticated against the tracking issue's repo; a writable agent-memory location. `TaskList` is used when present. |\n| `rate-limit-guard` | Claude Code's `CronCreate` / `CronDelete`, `python3`, and a session left open (or reopened) in the same worktree so the durable cron can fire. Run `/usage` first to learn your reset time. |\n| `resume-after-limit` | The same, plus `.claude/.rate-limit-guard.json` written by the guard — or an explicit `<command>` argument. |\n| `schedule` | Claude Code's `CronCreate` and `python3`. |\n| `worktree-spawn` | `git`, a writable parent directory, and the main repo as the working directory. Optional: a `git-crypt` key at `~/.config/git-crypt/<repo>.key` for auto-unlock. |\n| `worktree-teardown` | `git`, run from the main repo with the worktree path as an argument. |\n\n## Install\n\n### Claude Code\n\n```\n/plugin marketplace add dEitY719/session-skills\n/plugin install session@session-skills\n```\n\n### Codex\n\n```\ncodex plugin install dEitY719/session-skills\n```\n\n### Kimi CLI\n\n```\nkimi plugin install dEitY719/session-skills\n```\n\n### Hermes Agent\n\n```\nhermes plugins install dEitY719/session-skills\n```\n\n### OpenCode\n\nSee [`.opencode/INSTALL.md`](.opencode/INSTALL.md).\n\n### Gemini CLI / Antigravity\n\n```\ngemini extensions install https://github.com/dEitY719/session-skills\n```\n\nAntigravity (`agy`) shares `~/.gemini`, so it inherits the install.\n\n## Harness support\n\nThis repo is more harness-coupled than most of its siblings. Three of the eight\nskills exist only because Claude Code can schedule a future agent turn, so they\ndo not run anywhere else at all and refusing is the correct behaviour; three\nmore read the session TodoList and degrade rather than fail without it; only the\ntwo worktree skills are pure `git` and behave identically everywhere. The\nper-skill matrix, what each degraded cell means, and the two smaller gaps that\napply outside Claude Code are in\n[`docs/harness-support.md`](docs/harness-support.md). Every gap and its\nworkaround is documented per harness in\n[`harness-skills/references/`](https://github.com/dEitY719/harness-skills/tree/main/references);\nread the one file for the harness you are on.\n\nThe `lib/*.sh` helpers under `close/` are plain POSIX-friendly bash and run\nidentically on every harness. Call them; do not reimplement them.\n\n## Shared assets\n\nThis repo owns none — deliberately.\n\n- **Per-harness tool mappings** live in\n  [`harness-skills/references/`](https://github.com/dEitY719/harness-skills/tree/main/references)\n  (`{codex,kimi,gemini,antigravity,hermes,opencode}-tools.md`). That repo is\n  their sole owner; the other fourteen `*-skills` repos link there rather than\n  carrying copies, so one tool rename is one edit, not fifteen\n  (dotfiles #1410 F-5 / NF-2). The only condensed mirror here is\n  `.kimi-plugin/plugin.json`'s `skillInstructions`, because Kimi CLI cannot read\n  a reference file at load time — it points back to the canonical file.\n- **The reusable CI workflow** is\n  [`harness-skills/.github/workflows/skill-check.yml`](https://github.com/dEitY719/harness-skills/blob/main/.github/workflows/skill-check.yml)\n  (dEitY719/dotfiles#1410 D-10). See [CI](#ci).\n\n## Layout\n\nManifests live at the repo root and all point at one flat `skills/` directory:\n\n```\n.\n├── skills/{restart,close,handoff,rate-limit-guard,\n│           resume-after-limit,schedule,\n│           worktree-spawn,worktree-teardown}/\n│   ├── SKILL.md\n│   ├── references/\n│   ├── lib/                                    (close only)\n│   └── evals/                                  (restart only)\n├── .claude-plugin/{marketplace,plugin}.json    Claude Code\n├── .codex-plugin/plugin.json                   Codex\n├── .kimi-plugin/plugin.json                    Kimi CLI\n├── .hermes-plugin/{plugin.yaml,__init__.py}    Hermes Agent\n├── .opencode/plugins/session.js + INSTALL.md   OpenCode\n├── .agents/plugins/marketplace.json            Antigravity\n├── gemini-extension.json + GEMINI.md           Gemini CLI\n├── package.json\n├── CLAUDE.md · AGENTS.md -> CLAUDE.md\n└── LICENSE\n```\n\nOnly Claude Code understands a nested `plugins/<name>/skills/` layout. The other\nfive harnesses resolve manifests at the repo root and a skills tree at\n`./skills/`, so this repo keeps everything flat. See [`CLAUDE.md`](CLAUDE.md) for\nthe full rationale and contribution rules.\n\nSkill directory names dropped their old prefixes. In dotfiles these were\n`devx-restart`, `devx-session-close`, `ai-worktree-spawn` and so on; here the\nplugin name already carries that meaning, so `/session:devx-restart` would\nstutter where `/session:restart` reads cleanly (dEitY719/dotfiles#1410 F-4). Contrast\n`pkm-skills`, which *keeps* `obsidian-` and `karakeep-` because those name two\ndifferent external services inside one plugin.\n\nThe `.kimi-plugin/` manifest is pre-provisioned: Kimi CLI is not installed on the\nmaintainer's machines yet, and shipping the manifest now costs nothing and saves\na migration later.\n\n## CI\n\n[`.github/workflows/validate.yml`](.github/workflows/validate.yml) calls the\nreusable workflow owned by `harness-skills`:\n\n```yaml\njobs:\n  validate:\n    uses: dEitY719/harness-skills/.github/workflows/skill-check.yml@main\n    with:\n      plugin-name: session\n```\n\nIt validates manifests, skill frontmatter (the `name:` must be bare and match\nthe directory), progressive-disclosure line limits, the Codex description\nbudget, version agreement across all seven manifests, shell scripts, and the\nno-emoji rule. There is no local copy to keep in sync; a check added upstream\napplies here on the next run.\n\n## Provenance\n\nThese skills were extracted from\n[`dEitY719/dotfiles`](https://github.com/dEitY719/dotfiles)\n(`claude/skills/{devx-restart,devx-session-close,devx-session-handoff,devx-rate-limit-guard,devx-resume-after-limit,devx-schedule,ai-worktree-spawn,ai-worktree-teardown}`)\nas a content snapshot at source commit `b5f7fd1347e56c9a70e9b67ba15e7c5b7f1cf9ac`\n— no history rewriting. The dotfiles copies remain in place; they are removed in\nPhase 4 of that repo's migration. Behaviour is unchanged from the snapshot; only\nthe namespace moved, from `devx:` and `ai-worktree:` to `session:`.\n\nThis is Phase 2 of the dotfiles #1410 migration. `packaging-skills` was Phase 0,\nand `harness-skills` (Phase 1) is the sibling that owns the shared assets this\nrepo links to.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 13004,
  "sha": "f8821f0a8fd5276ed4c608c67eb807288050194445a13dcab0229ac88ecf4c79",
  "repo_slug": "deity719/session-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_deity719_session_skills_cd479b90/readme"
}