Skip to main content
skill CX Codex

hunt · orwa-mahmoud — Claude Code skill: what it does, how to install

The hunt Claude Code skill builds a Nightshift work shift from a project request. Give it a task and a number of hours, and it starts without asking for catalog choices.

MIT ★ 571 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add orwa-mahmoud/nightshift --skill hunt -a claude-code
Open on GitHub

What hunt does

hunt turns a project-work request into a shift assembled from the Nightshift catalog. When the request includes both an objective and a time budget, the agent selects suitable catalog entries and starts the shift. The owner sets the number of hours.

For an incomplete request, the agent asks only for the missing details. A request to review the plan first pauses execution for approval; otherwise, the configured execution mode applies. The skill uses the runtime/ns commands. If $NS/ does not exist on first use, it runs setup and asks at most four questions.

What it helps with

  • assemble a catalog-based shift for a project task
  • start work for a specified number of hours
  • collect missing details before execution
  • present a shift plan for approval

Example prompts for the agent

  • Improve this project for 5 hours.
  • Spend 8 hours clearing test debt.
  • Show me a plan for 3 hours of project work before starting.

How to install hunt

1Skills CLI (Vercel)

npx skills add orwa-mahmoud/nightshift --skill hunt -a claude-code

2Manually: put the files in place

~/.claude/skills/hunt/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/hunt/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about hunt

How do I install hunt in Claude Code?

Run npx skills add orwa-mahmoud/nightshift --skill hunt -a claude-code. The skill file is at ~/.claude/skills/hunt/SKILL.md.

What does hunt do?

It builds a work shift from the Nightshift catalog to match a project objective, then starts it. A request with an objective and a time budget goes straight to execution without presenting catalog choices.

When does hunt ask for the number of hours?

When the request gives a task but no duration. The agent asks one question, then continues once the hours are provided.

Source text

SKILL.md · MIT
---
name: hunt
description: Turn a request like "improve this project for 5 hours" into a shift from the ready catalog and start it, asking only for the hours when they are missing.
license: MIT
metadata:
  internal: true
---

Compose a shift for the host-opened project: settle the work, the ending, and the hours, then
either show it for approval or cut it and start.

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/hunt/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.

Read `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/compose/execution-modes.md` before composing: it
carries the state map, who selects work, when the clock starts, direct-mode authority, the tooling
policy, and how several entries become one shift. If `$NS/` does not exist yet, run Setup's flow
(`skills/setup/SKILL.md`, at most four questions) first, then continue with the same sentence.
Never send the owner away to run Setup.

## 0. Read the sentence first

The owner's sentence is binding intent. There is no keyword list.

An actionable objective with a number of hours, regardless of wording, is a complete prompt:
compose it and run it. Examples of a complete prompt:
*"enhance my project for 5 hours"*;
*"use the next 20 hours adding features and enhancing existing ones"*;
*"8 hours clear lint and test debt"*.

- Complete → Automatic. Do not offer catalog cards. Do not ask who selects, when to start, or "same
  as last time." It runs directly under the resolved `shift.execution` (`run-direct` unless the
  owner chose otherwise, or the sentence asks to see it first). Write the shift policy from the
  resolved tooling policy, no new elevation, and remembered verification, unless the sentence
  already granted a policy or allowance.
- An objective with no hours → ask exactly one question, *"How many hours?"*, and offer nothing
  else in it. The hours are the owner's; never choose them. Then continue as a complete prompt.
- Any other incomplete prompt → Ask only a field that is still missing, then continue.
- The owner asked to pick from the menu, or named Guided → section 1.

## 1. Ask who selects

Entries live one per file: the shipped ones in
`$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/compose/shifts/`, and the owner's in the
catalog folders [Owner knobs](https://github.com/orwa-mahmoud/nightshift/blob/main/docs/knobs.md#catalogs) describes. **Start with what the catalog holds, not with
every contract in it:**

```bash
"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" catalog-index
```

One line per entry — slug, ending, title, purpose — read straight from the files.
An entry added today is discovered today, and one that was deleted stops being offered. There is no second list to keep in
step, and the helper ranks nothing: which entries suit the objective is your judgement.

**Then read in full only the entries you are actually going to use** —
`ns catalog-index --path <slug>` prints the file in force, an owner's entry included. A complete
objective needs the two or three contracts it names, not thirty. Read a contract before you compose it — its
ending, refusals, verification and supported stacks bind the shift, and none of that is in the
index line. `shift-catalog.md` beside the folder explains the two endings and
carries the Maintainer night preset; it does not list the entries.

If the helper is missing or fails, list the directory and read the entries yourself: discovery is
the point, and a job that exists in the folder but never reaches the owner is the failure to
avoid.

Offer two first-class modes when the prompt did not already choose:

- **Guided** — one offer line per entry, with its ending marked, plus one line for any
  preset `shift-catalog.md` names. The index gives you every one of them; read a contract in full
  when the owner picks it, not before.
- **Automatic** — inspect the work target per `execution-modes.md` (in artifact mode that includes
  `$NS/receipts/`, not a git log) and compose the entries that support the stated objective.
  Quality, coverage, and dependency work do not hijack a feature or design objective. Show evidence
  only in review-first mode; run-direct does not pause.

**More than one may be chosen** — a night can clear the lint backlog and then hunt coverage until
the whistle. Respect every entry's compatibility restrictions when combining; never combine
entries that claim the same single-writer state.

Compose, cut and arm only through the Start preflight; it refuses, and names the repair, when the
work target cannot be resolved, work-mode is missing or malformed, or `$NS/receipts` exists but is
not a usable directory. Never `git init` a notes folder to get past a refusal.

The GitHub issue-hunt entry is offered with the rest of the catalog. It consumes only
drafting-table entries the Import issues skill created (canonical Source URL and
`Status: proposed`); list them by reading `$NS/staging/drafting-table.md`. Promote a selection by cutting
the item — never a copy — with
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" import-issues --promote …`,
or do the cut here when that helper cannot parse the file.
It does not replace defect hunt or product evolution, and never searches or writes back to GitHub.
Never select it when work mode is artifact.

The other repository-shaped jobs are out of scope there too:
Never select defect hunt when work mode is artifact.
Never select documentation drift when work mode is artifact.
Never select TODO and FIXME debt when work mode is artifact.
Never select coverage hunt when work mode is artifact.
Never select tooling quality-debt entries when work mode is artifact.

`ns normalize-output` and `ns inventory` are read-only reports a shift may
lean on when the host carries them — if present, optional, never required. The first turns a
supported tool format into one compact summary for the receipt and the ledger; the second lists
each workspace package's manager, lockfile, declared scripts, configs, and which named tools are
runnable. Automatic composes and works a shift without either.

## 2. Ask when execution starts

A complete prompt never asks this: it follows the resolved `shift.execution` (`run-direct` unless
the owner chose otherwise). A Guided or incomplete prompt asks **review first, or run directly?**,
prefilled from `shift.execution` — a choice independent from Guided or Automatic.

- **Review first** — discovery stays read-only and the clock starts only after approval.
- **Run directly** — start the clock once the tooling policy is settled and do not pause after
  discovery, under the direct-mode decision policy in `execution-modes.md`. Review-missing holds
  the clock until that plan is approved.

## 3. Ask the tooling policy and confirm tonight's shift policy

This is composition's one question for tonight's policy — Start never asks it. On a complete
Automatic prompt, skip the question and write the safe defaults from `execution-modes.md`, parking
any elevation gap. **The tooling policy is the owner's standing answer, not a default to re-pick:**
read the resolved value and carry it. With no explicit persistent choice, a complete prompt runs
under the built-in `auto-add` (existing-tools in artifact mode). A saved `auto-add` or `review-missing` survives an
objective that says nothing about tooling; a tonight-only `existing-tools` in the prompt overrides
it for that shift alone and changes nothing persistent. Carrying a policy forward grants no new
elevation — an allowance is still the owner's to give. Otherwise ask **before scanning**, and
before any compose, cut, or arm.

Read `$NS/run/work-mode` and the remembered project default with
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" shift-policy defaults-get`,
and run the permission preflight
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" preflight-needs`
against the entries this compose would select. Ask the single prefilled question in
`execution-modes.md`, folding every capability gap into it, then write the resolved policy with
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" shift-policy set --from-json -`. Persist a change as the new project default only when
the owner says to remember it (`defaults-set`). In review-first mode that policy is the only file
written before approval; in run-direct mode, arm as soon as it lands.

Artifact mode refuses repository-tool policies (`auto-add`, `review-missing`) and explains why — a
notes folder has no repository toolchain to add. Only existing-tools is valid there; if the
remembered default holds a repository-tool policy, keep existing-tools.

Under auto-add, capture the write surface before writing with
`"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" provision baseline --surface <rel> [<rel>...]` (one flag takes several paths, or repeat `--surface` per path), then install, smoke, `diff`, and
`rollback` when smoke or the tooling commit fails.

Then inspect, compose, cut, or arm. Under existing-tools, skip unavailable contracts even when
Guided selected them.

## 4. Establish the ending

Per the entry's declared ending:

- **Open-ended** — hours are REQUIRED. These have no natural end but the clock; a walkthrough may
  not start without a deadline. The entry's declared open-ended title is the source of truth.
- **Finite** — when hours were not already given, ask the ending as an explicit either/or: *until
  every finding is clear, or capped at N hours?* Both are valid; the work ends when the list is
  empty either way, and hours are only a safeguard against a backlog bigger than the night.

One deadline governs the whole shift, and Automatic always requires hours. On a mixed selection say
so in one line: the finite work runs first, and the open-ended job soaks up whatever time is left.

## 5. Ask for guided scope

> Anything specific about scope or approach?

Ask this in Guided mode; in Automatic the owner's sentence is the scope. Free text is skippable and
is where the useful shift is made: *"only `packages/api/`"*, *"use `getTestInstance()` from the
test package"*, *"one module — this becomes a single reviewable PR"*.
If a selected entry declares Owner instructions required, it is not skippable: ask, and refuse to
compose, cut, or arm that entry until the owner supplies a non-empty answer. Those entries are
Guided-only and are never selected in Automatic mode. Never edit the entry's own contract to fit
it; the owner's words become their own sub-bullet:

```text
 - **Owner instructions:** <verbatim, as written>
```

The entry's rules stay above it untouched. They enforce the shift contract — assert behaviour
rather than counts, gate green at every commit or artifact receipt, never silence instead of
fixing — and owner text adds constraints rather than replacing them.

## 6. Review or cut

In **review first**, print the items exactly as they will be written, with evidence, order, hours,
and ending, then ask for one approval. The preview is model prose: a no-write, no-clock simulation
of the resolved workspace and work target, the shift policy, why each entry serves the stated
objective, overlaps removed, rejected alternatives, and the stopping rule.
This is the last look before anything is armed. Write nothing before approval.

With the preview, ask one planning-depth question: "Before I write
these, want any of: evidence lines, an edge-case pass, a pre-mortem, an ordering and risk check, or
research? The default is none." Ask once per compose, never in run directly, and take one answer.
For the options picked, read `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/plan/menu.md`
and run only those; the order holds only the lines the owner keeps. A yes to shift-wide evidence
goes into tonight's policy under `receipts.evidence`. Evidence shows the work. check off leaves the tick alone, report names a missing file, and block keeps the stop open.

In **run directly**, do not ask again: write the order and immediately cut it into the active
shift. Record significant discovery and selection decisions in `$NS/inbox/parking-lot.md`.

On approval, run `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" scaffold work-orders`, which creates
`$NS/staging/work-orders.md` from its template the first time and keeps it after, then append to it —
hunt's own file; the drafting table stays the owner's room. Never clobber orders already sitting
there — append below them:

```text
## Work order — <ISO date time>
Hours: <N, or "none — finite">

- [ ] **<entry item, verbatim>**
 - **Owner instructions:** <if any>
```

The hours are inert while a review-first order sits here — the clock starts only at the cut, after
approval. In run-direct mode the order is cut immediately, so its clock starts now.

## 7. Start or park after review

After review-first approval, ask **start now, or park it for later?** Run-direct skips this
question and always starts now; choosing it was already explicit authorization.

On **now** — start the shift yourself, here, without making the owner type another command. Follow
the Start skill exactly, including its whole preflight and the unsupported-permission report
described in `execution-modes.md`. Then clear the stale markers and
**cut** the whole `## Work order` section out of `$NS/staging/work-orders.md` (heading, hours, and item —
do not leave an empty order heading behind), put only the item under `## Items` in the punch list
(a cut, never a copy — it must not exist in two places), and:

- for a product-evolution item (the standing loop or the owner walkthrough), run
  `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" scaffold product`, which creates
  `$NS/product/opportunity-map.md` and `$NS/product/product-research.md` from their templates and
  keeps any already there;

- write `$NS/run/deadline` as a UNIX epoch from the recorded hours — `date +%s` plus hours*3600 on
  POSIX, or `Get-NSUnixTime` plus hours*3600 after
  `Import-Module "$NIGHTSHIFT_PLUGIN_ROOT\lib\Nightshift.psm1" -Force` on native Windows;
- **arm the gate** with `touch "$("$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" path armed)"` on POSIX, or
  `New-Item -ItemType File -Force (& "$NIGHTSHIFT_PLUGIN_ROOT\runtime\windows\ns.ps1" path armed)` in native Windows PowerShell;
- log the start and run the binding probe (`: nightshift-binding-probe` on POSIX,
  `$null = 'nightshift-binding-probe'` on native Windows);
- classify Codex `$NS/run/.shift-session` line 1 with `ns_codex_identity_kind` from
  `$NIGHTSHIFT_PLUGIN_ROOT/lib/lib.sh`, or `Get-NSCodexIdentityKind` after importing
  `Nightshift.psm1` on native Windows, before arming the watchman or beginning item work;
- **arm the watchman** as the Start skill requires, with `ns start-watchman` for this host; never
  begin item work unless it reports the watchman armed.

An empty `## Items` section still keeps the Shift contract and Gates; they bind the cut item.
Record leftover campaign rules in `$NS/inbox/parking-lot.md` when they are not this order's.

On **later** — the order stays parked in `$NS/staging/work-orders.md` with its hours, costing nothing. It
arms nothing and the gate stays inert. Start (`/nightshift:start` on Claude Code, or ask Nightshift
to start on Codex) will offer it when the owner is ready.

© orwa-mahmoud · MIT · orwa-mahmoud/nightshift

Similar skills

SKILL.md skills catalog →

hunt by other authors comes first.

hunt tw93 hunt pinpoints root causes before touching code when an app crashes or regresses. Enforces reproducible evidence and verification before applying any fix. CX Codex +1 15,300installs hunt H-mmer Conducts targeted vulnerability hunting by validating scope, fingerprinting stacks, and dispatching exploit tests. CX Codex +1 ★ 1,298repo stars product-hunt-launch 101-skills Walks you through a Product Hunt launch: tagline, gallery order, maker comment and the day's timing, with images and research run through the belt CLI. CX Codex +1 65,800installs secops-hunt official Google LLC The secops-hunt skill for Claude Code supports threat hunts in Google SecOps using UDM events. It tests hunting hypotheses, searches historical data for IoCs, and surfaces unusual activity. CX Codex +1 1,900installs hunt-a-handle UseOSINT hunt-a-handle sweeps a username across hundreds of platforms with sherlock, maigret and WhatsMyName, then helps you tell real accounts of one person from lookalikes. CX Codex +1 1,900installs product-hunt-launch-plan ognjengt Builds a step-by-step Product Hunt launch plan for your product, from prep through launch day and the follow-up. CX Codex +1 1,300installs bug-hunt-swarm Dimillian bug-hunt-swarm investigates bugs with parallel sub-agents and ranks likely root causes. Use it for regressions, crashes, flaky behaviour, and failures when code edits must wait. CX Codex +1 767installs regression-hunt trailofbits regression-hunt — a skill for Claude Code that investigates regressions in PRs and commits. It coordinates error-hunting campaigns and resumes saved progress. CX Codex +1 685installs

From the same set17

The whole set →
plan This Claude Code skill opens a planning room to explore a project and shape the work with its owner. Implementation waits until the owner deliberately leaves the room. CX Codex +1 ★ 571repo stars plan-exit The plan-exit Claude Code skill checks whether plan mode is closed and names the next step toward implementation. It reads the room status and staged items. CX Codex +1 ★ 571repo stars nightshift The nightshift Claude Code skill works through a project punch list during an autonomous shift. Start it with a request to work on the project, with or without a time budget. CX Codex +1 ★ 571repo stars import-issues The import-issues Claude Code skill stages selected GitHub issues as project drafts. It previews each issue before asking which ones to add. CX Codex +1 ★ 571repo stars doctor The doctor Claude Code skill diagnoses a Nightshift project and reports detected issues. Run it to inspect the workspace, shift state, markers, and deadlines. CX Codex +1 ★ 571repo stars customize The customize Claude Code skill displays Nightshift settings, templates, and catalog entries on one screen. It changes only the values the project owner names. CX Codex +1 ★ 571repo stars archive Files completed Nightshift records into structured archive folders. Active project directories keep only open tasks and unresolved records. CX Codex +1 ★ 571repo stars install-nightshift The install-nightshift Claude Code skill installs the Nightshift plugin with its hooks and runtime. It checks Claude Code, Codex, and Cursor before guiding the setup. CX Codex +1 ★ 571repo stars

Project sponsors

Companies that keep this analytics open