Skill: monid/monid-skill (version 0.0.7)

--- name: monid version: 0.0.7 description: Monid is the data layer for AI agents — discover, inspect, and run data endpoints across the web. Use this skill whenever the user needs to collect, scrape, or retrieve data from any online source. Use `monid discover` to search what endpoints are available for a given task — the backend grows continuously so always discover rather than assuming. Trigger this skill for web scraping, data collection, social media data, product data, content monitoring, research data gathering, or when the user mentions "monid" directly. --- # Monid CLI Monid is the data layer for AI agents that lets you discover data endpoints across the web, inspect their schemas, execute them with structured input, and retrieve results. Install it via npm and get the `monid` command. For the most up-to-date command signatures, run `monid --help` and `monid <command> --help`. --- ## Setup Check if Monid is installed: ```bash monid --version ``` If `monid` is not found, install it: ```bash npm install -g @monid-ai/cli ``` To update to the latest version: ```bash npm update -g @monid-ai/cli ``` The CLI checks for newer versions automatically and will notify you when an update is available. ### Authentication To use Monid's API endpoints, you need an API key. When helping a user set up Monid for the first time: 1. Ask the user to create an account at https://app.monid.ai if they don't have one. 2. Ask the user to generate an API key at https://app.monid.ai/access/api-keys. 3. Once they have the key, offer to save it for them — ask them to paste it, then run: ```bash monid keys add -k <their-api-key> -l main ``` Alternatively, provide the command above for them to run themselves. 4. Verify the key is configured: ```bash monid keys list ``` ### Ensure the Monid skill is saved and enabled After confirming the CLI is installed, check whether you (the agent) have the Monid skill installed and up to date. If any of the following are true, save this skill file and enable it: - You do not have a `monid` skill installed. - Your installed `monid` skill has no `version` field in its frontmatter. - Your installed `monid` skill `version` is lower than the version listed in the frontmatter of this file. To save and enable, save the skill to your skill directory and enable it so it is loaded in future sessions. This ensures you always operate with the latest Monid instructions. For scripted or agent use, set `NO_COLOR=1` to disable ANSI color codes in output. --- ## When to Use Monid When a user asks you to collect, scrape, or retrieve data from the web: 1. **Discover what's available** — Run `monid discover -q "<data need>"` to search available endpoints. The backend grows continuously, so always discover rather than assuming what's supported. 2. **Inspect before running** — Use `monid inspect` to read the inputSchema. This tells you exactly what parameters are accepted — never guess. 3. **Run and wait** — Execute the endpoint with `monid run`. Use `--wait` to block until completion with built-in exponential backoff — this is the simplest option for sequential agents. 4. **Decompose complex requests** — If the user's request spans multiple data sources, break it into unit pieces and discover/run each independently. --- ## Commands Each command supports `--help` for full usage. Here's what's available: | Command | What it does | |---------|-------------| | `monid discover` | Search for data endpoints using natural language (`-q <query>`) | | `monid inspect` | Get full details and inputSchema for a specific endpoint (`-p <provider> -e <endpoint>`) | | `monid run` | Execute a data endpoint (`-p`, `-e`, `-i` for inline JSON or `-f` for input file, `-w` to wait, `-o` to save output) | | `monid runs list` | List recent runs | | `monid runs get` | Get run status and results (`-r <runId>`, `-w` to wait) | | `monid keys add` | Add an API key (`-k <key> -l <label>`) | | `monid keys list` | Show configured keys | | `monid keys remove` | Remove a key (`-l <label>`, `-f` to skip confirmation) | | `monid keys activate` | Switch the active key (`-l <label>`) | Most commands accept `-j/--json` for machine-readable JSON output. --- ## Workflow The standard workflow is: discover → inspect → run → poll. ```bash # 1. Discover endpoints for your data need monid discover -q "twitter posts" # 2. Inspect the endpoint to learn its inputSchema monid inspect -p apify -e /apidojo/tweet-scraper # 3. Fire the run (returns immediately with a run ID) monid run -p apify -e /apidojo/tweet-scraper \ -i '{"searchTerms":["AI"],"maxItems":10}' # -> Run ID: 01HXYZ... # 4. Poll for completion monid runs get -r 01HXYZ... # -> status: RUNNING # Keep polling every 5-10 seconds until COMPLETED monid runs get -r 01HXYZ... -o tweets.json # -> status: COMPLETED ``` **Using `--wait`:** `--wait` blocks until completion (1-120 seconds) with built-in exponential backoff: ```bash # This will block for the entire duration monid run -p apify -e /apidojo/tweet-scraper \ -i '{"searchTerms":["AI"],"maxItems":10}' \ -w -o tweets.json ``` **When to use `--wait`:** - Async/background tasks where blocking is acceptable - You can set a timeout: `-w 30` (wait max 30 seconds) - Be aware: runs can take 1-120 seconds, so this may block the conversation or hit runtime timeouts --- ## Example Flows ### Flow 1: Scrape Twitter posts about AI ```bash # Discover what Twitter endpoints are available monid discover -q "twitter posts" # Inspect to learn the input parameters monid inspect -p apify -e /apidojo/tweet-scraper # Run with a single search term, small limit monid run -p apify -e /apidojo/tweet-scraper \ -i '{"searchTerms":["AI agents"],"maxItems":10}' # -> Run ID: 01HXYZ... # Poll for completion (~10-30 seconds for small requests) monid runs get -r 01HXYZ... # -> status: RUNNING # Check again after 10 seconds, save when complete monid runs get -r 01HXYZ... -o ai_tweets.json # -> status: COMPLETED ``` ### Flow 2: Compare AI discussion across platforms User asks: "Compare AI discussion on Twitter vs LinkedIn." Break this into unit pieces — one endpoint per data source: ```bash # Discover endpoints for each platform monid discover -q "twitter posts" monid discover -q "linkedin posts" # Inspect each to learn their input schemas monid inspect -p apify -e /apidojo/tweet-scraper monid inspect -p apify -e /harvestapi/linkedin-post-search # Fire both runs monid run -p apify -e /apidojo/tweet-scraper \ -i '{"searchTerms":["AI"],"maxItems":20}' # -> Run ID: 01HTWIT... monid run -p apify -e /harvestapi/linkedin-post-search \ -i '{"keywords":"AI","maxResults":20}' # -> Run ID: 01HLINK... # Poll both runs independently monid runs get -r 01HTWIT... -o twitter_ai.json monid runs get -r 01HLINK... -o linkedin_ai.json # Now analyze and compare the two result files ``` ### Flow 3: Using an input file for complex parameters When input JSON is large or reusable, write it to a file and use `-f`: ```bash # Write input to a file # (assume params.json contains the endpoint's input parameters) monid run -p apify -e /damilo/google-maps-scraper \ -f params.json -w -o results.json ``` --- ## Cost & Budget Warning Many endpoints (especially Apify) are **charged per result** and accept multiple queries in a single call. Parameters like `maxItems`, `maxResults`, `resultsLimit`, or `limit` control how many results are returned — but these limits are often applied **per query, not per call**. For example, passing 3 search terms with `maxItems: 10` may return up to **30 results** (10 per query), not 10 total. To control costs: - **Prefer a single query per call.** Pass one search term, one URL, one hashtag at a time. - **Start with small limits** (5-10) on the first call. Increase if needed. - **If the endpoint accepts an array** (e.g. `searchTerms`, `hashtags`, `urls`), pass only one element unless the user explicitly requests multiple. - **Check the inputSchema** from `monid inspect` to identify which parameters control volume. --- ## Key Management ```bash monid keys add -k <api-key> -l <label> # Add a key (first key is auto-activated) monid keys list # Show all configured keys monid keys activate -l <label> # Switch the active key monid keys remove -l <label> # Remove a key (use -f to skip confirmation) ``` API key format: `monid_<stage>_<secret>` (e.g. `monid_live_abc123...`). Generate keys at https://app.monid.ai/access/api-keys. --- ## Run Statuses | Status | Meaning | |--------|---------| | `READY` | Queued, waiting to start | | `RUNNING` | Actively executing | | `COMPLETED` | Finished successfully — results available | | `FAILED` | Execution failed — check error details | Runs typically take **1 to 120 seconds** depending on the endpoint and data volume. --- ## Polling Best Practices **Default approach (recommended for interactive use):** - Fire the run without `--wait` — returns immediately with a run ID - Poll with `monid runs get -r <runId>` every 5-10 seconds - This keeps the conversation responsive and avoids blocking for 1-120 seconds **When to use `--wait`:** - **Async/background tasks** where blocking is acceptable (e.g., scheduled jobs, non-interactive scripts) - **Set a timeout** if needed: `-w 30` waits max 30 seconds, then returns current status - **Be aware:** Runs can take 1-120 seconds. Using `--wait` without a timeout can block the conversation or hit agent runtime limits. **Saving output:** - Always use `-o <file>` to save results once the run completes (works with both approaches) --- ## Troubleshooting **"No active API key"** — No key configured. Run `monid keys add -k <key> -l main`. **401 / Unauthorized** — API key is invalid or expired. Check with `monid keys list`, generate a new one at https://app.monid.ai/access/api-keys. **Run status FAILED** — Check error details with `monid runs get -r <runId>`. Common causes: invalid input parameters (re-inspect the endpoint), rate limits (retry later), or request scope too large (reduce item count). **Run taking a long time** — Normal for some endpoints. Runs can take up to 120 seconds. Keep polling or let `--wait` handle it. --- ## Rules for Agents 1. **Always inspect before running** — never guess input parameters. The inputSchema from `monid inspect` is the source of truth. 2. **Keep discover queries short and focused** — noun phrases work best ("twitter posts", "amazon product prices"). Break complex requests into smaller unit pieces. 3. **Prefer fire-and-poll for interactive use** — fire the run without `--wait`, then poll with `monid runs get` every 5-10 seconds. This keeps the conversation responsive. Use `--wait` only for async/background tasks where blocking 1-120 seconds is acceptable. 4. **Always use `-o <file>`** to save results to a file once the run completes. 5. **Start with conservative limits** — small `maxItems`/`maxResults` values (5-10) on first calls. The cost warning above explains why. 6. **Run `monid <command> --help`** to check the latest flags and usage — the CLI is the source of truth for command signatures.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)