cosmicstack-labs/staff-scheduler
>- Build optimized staff schedules that match coverage to demand while respecting labor budgets, employee availability, and local labor laws. Handles shift swaps, time-off requests, and identifies over/under-staffing before it happens.
npx skills add https://github.com/cosmicstack-labs/mercury-agent-skills --skill staff-scheduler
Labor is typically the second-largest cost (after COGS) for any shop or restaurant — often 25-35% of revenue. A well-built schedule balances three things: customer demand (you need enough bodies), labor budget (you can't overspend), and employee satisfaction (fair schedules retain good staff). The Staff Scheduler skill automates this balancing act.
Ask the user for:
If they don't have a sales forecast:
> "Let me look at your sales data from the same period last week/month and project forward. I'll adjust for any known events or holidays."
Available Labor $ = Projected Sales × Target Labor %
Hour Budget = Available Labor $ ÷ Average Hourly Rate (blended)
Example:
> "Next week's projected sales: $28,000. At a 28% labor target, you have $7,840 to spend on wages. With a blended rate of $18/hr across all roles, that's 435 hours total."
Break each day into shifts (e.g., opening, mid, closing) and assign required headcount per role:
| Day | Shift | Servers Needed | Cooks Needed | Cashiers Needed | Projected Sales |
|-----|-------|---------------|-------------|----------------|----------------|
| Mon | Open | 1 | 1 | 1 | $1,200 |
| Mon | Mid | 2 | 1 | 2 | $2,800 |
| Mon | Close | 2 | 2 | 1 | $2,000 |
| Tue | Open | 1 | 1 | 1 | $1,100 |
Recommendation engine assigns staff based on:
Output a clean weekly schedule:
WEEK OF: Mar 10-16, 2025
MONDAY MAR 10
Open (8am-2pm): Sarah (S), Mike (C), Jen (Ca)
Mid (2pm-6pm): Sarah (S), Tom (S), Mike (C), Jen (Ca)
Close (6pm-11pm): Tom (S), Lisa (S), Dave (C), Raj (C), Amy (Ca)
TUESDAY MAR 11
Open (8am-2pm): Lisa (S), Dave (C), Amy (Ca)
...
LABOR SUMMARY
Total Hours Scheduled: 432 / 435 (99.3% utilization)
Total Labor Cost: $7,776 / $7,840 (99.2% of budget)
Labor Cost %: 27.8%
Avg Hourly Rate: $18.00/hr
Highlight any issues:
> ⚠️ Warning: Monday close is overstaffed by 1 server. Consider moving Tom to Tuesday open to reduce overtime risk.
> ⚠️ Warning: Friday projection is conservative. If sales exceed $4,200, you'll need to add a 3rd cook.
When a staff member requests time off or wants to swap:
Example:
> "Sarah requested Saturday off. She's currently scheduled for the close shift. Available replacements: Tom (already at 35 hrs — would trigger overtime), Lisa (at 28 hrs, available). Recommend swapping Lisa into Saturday close and moving Sarah to Tuesday mid if she's available."
Before finalizing, scan for labor law violations:
> ✅ Compliance check passed. No overtime, all meal breaks accounted for, no minor scheduling issues.
> "The schedule is ready. Would you like me to share it with the team? I can highlight any changes from last week so staff can quickly spot what's different."
| Phrase | What Happens |
|--------|-------------|
| "Build next week's schedule" | Full workflow: gather data → calculate budget → build → check → publish |
| "I need a schedule for [date range]" | Builds schedule for a specific period |
| "Check my labor cost" | Analyzes current schedule against labor budget |
| "[Name] needs time off on [date]" | Processes time-off request and finds coverage |
| "Swap [name1] and [name2] on [date]" | Validates and executes a shift swap |
| "Am I overstaffed tomorrow?" | Compares scheduled hours vs projected demand for next day |
| "Show me overtime risks" | Flags any employees approaching overtime thresholds |
*"A great schedule makes the business run right and the team feel right. Get both."*
Take cosmicstack-labs/staff-scheduler from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.