# Service Creator

> Guide for creating background monitoring services that can proactively notify users

- Skill: `nevamind-ai/service-creator` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add nevamind-ai/service-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nevamind-ai/service-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: NevaMind-AI (https://skillmd.com/u/nevamind-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nevamind-ai/service-creator

---


# Service Creator Skill

This skill guides you on how to create background services that monitor data and proactively notify users.

**Reference documents directory**: `{{SKILL_DIR}}/reference/`

When you need detailed information on a specific topic below, use `read_file` to load the corresponding reference document. Do NOT read all references upfront — only load what you need for the current step.

| Reference File | When to Read |
|----------------|--------------|
| `reference/architecture.md` | Before designing a new service's filtering logic |
| `reference/dry-run.md` | When implementing dry run mode or verifying dry run output |
| `reference/modification.md` | When modifying an existing service |
| `reference/guidelines.md` | For best practices and example conversations |
| `reference/templates-minimal.md` | When writing service code (recommended starting point) |
| `reference/templates-stock-monitor.md` | When building a data-monitoring service with local filtering |
| `reference/templates-python-monitor.md` | When building a Python monitoring service |
| `reference/templates-reminder.md` | When building a reminder/time-based service |

## When to Use

Create a service when the user asks you to:
- Monitor something continuously (stocks, websites, APIs, files, etc.)
- Get notified when certain conditions are met
- Run periodic checks or tasks
- Watch for changes or events

**Examples of user requests:**
- "Help me monitor XX stock, notify me if it drops more than 5%"
- "Watch this API endpoint and tell me when it returns data"
- "Check my server status every 5 minutes"
- "Monitor this folder for new files"

## Architecture Overview

Services use a **two-layer filtering** pattern: Local Rules Filter → Invoke API (LLM Evaluation).
Read `reference/architecture.md` for full details when designing filter logic.

## Service Creation Workflow

### Step 0: Runtime Availability Check (Automatic)

When you call `service_create`, the system automatically checks if the required runtime (Node.js or Python) is available. If not available, the tool returns an error.

**When runtime is missing:**
1. Ask the user if they want you to install it
2. If yes, try to install using methods that DON'T require sudo:
   - **macOS**: Use Homebrew (`brew install node` / `brew install python3`) - no sudo needed
   - **If no Homebrew**: Install Homebrew first, or use nvm/pyenv
   - **Linux/Windows**: Explain to user that installation requires manual steps (sudo password or admin rights)
3. After installation succeeds, retry `service_create`

**Note**: You cannot use sudo or su commands as they require password interaction. Only use installation methods that work without elevated privileges.

### Step 1: Create Service Metadata

Use the `service_create` tool with:
- `name`: Human-readable name
- `description`: What the service does
- `type`: Choose based on whether the task has a definite end:
  - `"longRunning"`: Never exits, runs indefinitely (e.g., "monitor stock price every 30s", "wake me up every day at 8am", "send weekly report every Monday")
  - `"scheduled"`: Completes and exits after task is done (e.g., "remind me at 4:30pm today", "remind me to drink water 3 times", "notify me tomorrow morning")
- `runtime`: `"node"` or `"python"`
- `entryFile`: Entry file name (e.g., `"index.js"` or `"main.py"`)
- `schedule`: For scheduled services, interval like `"*/5"` (every 5 minutes)
- `userRequest`: The user's original request (verbatim)
- `expectation`: What should trigger a notification

### Step 2: Write Service Code

After creating the service, write the code to the returned `servicePath`.

**Before writing code**: Read `reference/templates-minimal.md` for the recommended pattern. For more complex scenarios, read the appropriate full template.

**Pre-built invoke helper**: The `service_create` tool automatically generates an invoke helper file in the service directory:
- **Node.js**: `invoke.js` — use `const { invoke, dryRunResult, DRY_RUN, SERVICE_ID } = require('./invoke');`
- **Python**: `invoke.py` — use `from invoke import invoke, dry_run_result, DRY_RUN, SERVICE_ID`

**Invoke API uses named parameters** (NOT positional args):
- **Node.js**: `await invoke({ context: CONTEXT, summary: '...', details: '...', metadata: {} })`
- **Python**: `invoke(context=CONTEXT, summary='...', details='...', metadata={})`

This eliminates the need to copy-paste the invoke boilerplate. Just import and use it.

**CRITICAL: Service Code Requirements**

1. **Service lifecycle depends on type**:
   - `longRunning`: Never exit - keep running indefinitely with `setInterval`
   - `scheduled`: Exit with `process.exit(0)` after task completion (e.g., reminder sent, N executions done)
2. **Use the pre-built invoke helper** - Import from `./invoke` instead of writing your own HTTP client
3. **Implement local filtering first** - Use algorithms/rules to filter data before calling API
4. **Set appropriate thresholds** - Use slightly lower thresholds than user specified to catch edge cases
5. **Only call invoke when conditions are potentially met** - Save LLM tokens for important decisions
6. **Include context** - Pass the user's original request and expectations to LLM
7. **Validate external API responses** - Always check HTTP status code AND response structure before accessing nested properties. External APIs may return rate limit errors, unexpected JSON, or HTML error pages.
8. **Handle errors gracefully** - Wrap all API calls in try-catch and log meaningful error messages. Don't let the service crash due to temporary API failures.
9. **Respect rate limits** - Free APIs often have rate limits (e.g., 10-30 requests/minute). Don't poll too frequently.
10. **Implement dry run mode** - The service MUST support dry run mode. Read `reference/dry-run.md` for the specification and patterns.
11. **Only use built-in modules** - Only use Node.js or Python standard library modules (http, https, fs, os, json, urllib, etc.). Do NOT use third-party packages (no axios, requests, cheerio, etc.) to avoid dependency issues.

**IMPORTANT**: Use `setInterval()` (Node.js) or loops (Python) to keep the service running. For `scheduled` type, call `process.exit(0)` when the task is complete.

### Step 3: Verify with Dry Run (MANDATORY)

After writing the service code, you MUST run `service_dry_run` to verify it works. Read `reference/dry-run.md` for full verification criteria, iteration rules, and failure handling.

### Step 4: Start the Service

Only after a successful dry run, use `service_start` with the serviceId to start the service.

## Modifying Existing Services

When modifying a service, read `reference/modification.md` first — it describes the critical synchronization rules between code, CONTEXT, and service.json.

## Available Tools

- `service_create` - Create a new service
- `service_dry_run` - **Run a service in dry-run mode to verify it works (MANDATORY before starting)**
- `service_list` - List all services and their status
- `service_start` - Start a service (only after successful dry run)
- `service_stop` - Stop a service
- `service_delete` - Delete a service
- `service_get_info` - Get detailed service information