jobs/
├── README.md                 # This document
├── README.zh.md              # Chinese version
├── spec/
│   └── jobs-spec.md          # Jobs specification
├── template/
│   └── JOB.md                # Job template
├── jobs/                     # Example Jobs
│   ├── npm-global-update/
│   ├── claude-news-collect/
│   └── todo-night-executor/
└── .claude-plugin/
    └── marketplace.json      # Claude Code plugin configuration

### Core Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Unique identifier for the job (lowercase, hyphen-separated) |
| `description` | Yes | Description of what the job does and when to use it |
| `cron` | Yes | Cron expression defining the schedule |
| `condition` | No | Execution condition (script path or natural language description) |
| `allowedSkills` | No | List of Skills allowed for this job |
| `timeout` | No | Maximum execution time in minutes |
| `retry` | No | Number of retries on failure |
| `tags` | No | Tags for organizing and filtering jobs |

### Cron Expression

Common examples:
- `0 9 * * *` - Every day at 9 AM
- `0 9 * * 1` - Every Monday at 9 AM
- `0 0 * * *` - Every day at midnight
- `*/30 * * * *` - Every 30 minutes

## Creating Jobs with Skills

### Using job-creator Skill

Trigger phrases: `create job`, `new job`, `job creator`

When you express an automation need, the job-creator Skill will:

1. Understand your automation intent
2. Generate an appropriate job name and cron schedule
3. Create `~/.agents/jobs/<name>/JOB.md` with proper structure
4. Optionally register it with `jobs add`

The Skill uses the template structure and validates through the CLI to ensure compatibility.

### Using jobs-scheduler Skill

Trigger phrases: `/jobs`, `jobs list`, `show jobs`

This Skill reads the global registry at `~/.agents/jobs.json` and displays:
- All registered jobs with their cron schedules
- Current status (enabled/disabled)
- Recent execution history
- Jobs needing attention (failing, disabled)

## How Jobs Are Consumed

Jobs support two execution modes:

### 1. Local Daemon Execution (Shell-based)

The daemon (`jobs daemon start`) runs locally and:

1. **Cron Check** - Every 15 seconds, checks for due jobs
2. **Condition Check** - If a condition is specified:
   - If it's a script path (starts with `./` or `/`, or ends with `.sh`), executes the script
   - If the script returns non-zero, the job is skipped
   - Natural language conditions require AI evaluation (skip in daemon mode)
3. **Command Extraction** - Extracts bash/sh/shell code blocks from JOB.md
4. **Shell Execution** - Executes commands using zsh with timeout control
5. **Result Recording** - Updates status, history, and next run time in `jobs.json`

**Flow:**

### 2. Claude Scheduled Task Execution (AI-based)

`jobs sync` converts enabled jobs to Claude scheduled tasks:

```json
{
  "id": "abc123",
  "cron": "0 9 * * *",
  "prompt": "## Scheduled Job: my-job\n\nRead and follow instructions in /path/to/JOB.md...",
  "recurring": true
}

┌──────────────┐
│    Start     │
└──────┬───────┘
       ▼
┌──────────────┐
│ Check Cron   │◄──────────────────┐
│  Is due?     │                   │
└──────┬───────┘                   │
       │                           │
   ┌───┴───┐                       │
   │  No   │ Yes                   │
   ▼       ▼                       │
┌──────┐ ┌──────────────┐         │
│Wait  │ │Check Condition│         │
└──┬───┘ └──────┬───────┘         │
   │            │                  │
   │        ┌───┴───┐              │
   │        │  No   │ Yes           │
   │        ▼       ▼              │
   │   ┌──────┐ ┌──────────────┐  │
   │   │Wait  │ │ Execute Job  │  │
   │   └──┬───┘ └──────┬───────┘  │
   │      │            │           │
   │      └────────────┼───────────┘
   │                   │
   └───────────────────┘

┌─────────────────────────────────────────┐
│                  Jobs                    │
│  ┌─────────────────────────────────┐    │
│  │  Cron Scheduling + Condition    │    │
│  │  Checking (Out of loop)         │    │
│  └──────────────┬──────────────────┘    │
│                 │                        │
│                 ▼                        │
│  ┌─────────────────────────────────┐    │
│  │         Skills Composition      │    │
│  │  (In loop / Agent loop)         │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘

## More Information

- [Specification](./spec/jobs-spec.md) - Complete Jobs specification
- [Template](./skills/job-creator/templates/JOB.md) - Template for creating new Jobs
- [Example Jobs](./jobs/) - View more examples

## Related

- [Jobs Over Skills](https://homyzone.pages.dev/blogs/aigc/jobs-over-skills)

Core insight: **Scheduled tasks are an important way to achieve automation and autonomous evolution.**