diff --git a/AGENTS.md b/AGENTS.md index 7121106f0..ded8c0c60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -159,6 +159,7 @@ feature area, the corresponding skill **must** be updated in the same PR. | Config format, daemon health, logs, MCP wiring, diagnostics CLI, doctor | `self-diagnostics` | | Skill file format, discovery, authoring workflow | `skill-authoring` | | Tool definitions, CLI commands, grant categories, search_tools, scheduling tools | `capability-reference` | +| Search tool behavior, citation policy, web_search/web_fetch usage guidance | `search-citation` | **Workflow:** 1. Edit the skill source at `feeds/skills/.system/files/{name}/{version}.md` diff --git a/feeds/skills/.system/files/capability-reference/1.1.0/SKILL.md b/feeds/skills/.system/files/capability-reference/1.1.0/SKILL.md new file mode 100644 index 000000000..1cb768290 --- /dev/null +++ b/feeds/skills/.system/files/capability-reference/1.1.0/SKILL.md @@ -0,0 +1,177 @@ +--- +name: capability-reference +description: "Quick-lookup catalog of all built-in tools, CLI commands, tool grant categories, scheduling syntax, and MCP discovery. Read when unsure what tools or commands are available." +metadata: + author: netclaw + version: "1.1.0" + triggers: what can I do | available tools | CLI commands | how to schedule | tool grants | MCP discovery | list capabilities +--- + +## Session Context + +Each turn injects the current session ID and channel info into the system +prompt. Use the session ID to: + +- reference yourself in scheduled reminders +- correlate with `netclaw sessions` output for diagnostics +- identify which session is running during troubleshooting + +## Built-in Tools by Grant Category + +### builtin (always granted) + +| Tool | Purpose | +|------|---------| +| `search_tools` | Discover and load MCP tools by keyword or server | +| `store_memory` | Save knowledge to cross-session memory | +| `find_memories` | Search memory (returns IDs, titles, snippets) | +| `get_memories` | Load full memory content by ID | +| `update_memory` | Edit or delete a memory by ID | +| `lookup_slack_user` | Find Slack user by name/email, returns user ID | +| `send_slack_message` | Send message to Slack channel or DM | + +### web + +| Tool | Purpose | +|------|---------| +| `web_search` | Search the web, returns titles/URLs/snippets | +| `web_fetch` | Fetch URL, save text to local file, return preview | + +### file + +| Tool | Purpose | +|------|---------| +| `file_read` | Read file contents as text | +| `file_write` | Write content to file, creates parent dirs | +| `attach_file` | Attach a file to send to the user | + +### shell + +| Tool | Purpose | +|------|---------| +| `shell_execute` | Run shell command with timeout, returns stdout/stderr | + +### scheduling + +| Tool | Purpose | +|------|---------| +| `set_reminder` | Schedule one-shot, interval, or cron reminders | +| `list_reminders` | List reminders with IDs, status, next fire times | +| `cancel_reminder` | Delete a reminder by ID | + +## Tool Grant System + +Sessions receive a set of granted tool categories. Tools outside the grant set +are unavailable for that session. `builtin` is always granted. Other categories +(`web`, `file`, `shell`, `scheduling`) are granted per ACL configuration in +`netclaw.json`. + +## MCP Discovery (search_tools) + +MCP tools are not loaded into the prompt by default. Use `search_tools` to +discover and load them: + +``` +search_tools(query: "servers") # list all MCP servers +search_tools(query: "all", server: "memorizer") # browse all tools in one server +search_tools(query: "email") # keyword search across all servers +``` + +After a search returns matching tools, those tools become callable. If no exact +match is found, `search_tools` suggests similar tools. + +Generated MCP catalogs are cached at `identity/tooling/shadow/mcp/.md`. + +## Scheduling Quick Reference + +`set_reminder` accepts three schedule types: + +| Type | Schedule value examples | +|------|----------------------| +| `once` | `"30m"`, `"2h"`, `"2026-03-15T14:30:00Z"` | +| `interval` | `"30m"`, `"6h"`, `"1d"` | +| `cron` | `"0 */6 * * *"`, `"0 9 * * MON-FRI"` | + +Key parameters: `name` (human-readable ID), `prompt` (instructions to execute), +`schedule_type`, `schedule`, `report_to_channel` (optional Slack channel for +results), `notify_instructions` (optional output formatting guidance). + +The agent can reference its own session ID when creating reminders to tie +scheduled work back to the originating conversation. + +## CLI Commands + +### Interaction + +| Command | Purpose | +|---------|---------| +| `netclaw chat` | Interactive TUI chat session | +| `netclaw chat --resume ` | Resume existing session by ID | +| `netclaw sessions` | Browse and resume recent sessions (TUI) | +| `netclaw sessions --once` | List sessions and exit (plain text or `--json`) | +| `netclaw -p "prompt"` | Headless single-prompt mode | + +### Daemon + +| Command | Purpose | +|---------|---------| +| `netclaw daemon start` | Start daemon as background process | +| `netclaw daemon stop` | Stop daemon gracefully | +| `netclaw daemon status` | Show daemon process status | +| `netclaw daemon install` | Install systemd user service (Linux) | +| `netclaw daemon uninstall` | Remove systemd user service | + +### Diagnostics + +| Command | Purpose | +|---------|---------| +| `netclaw doctor` | Offline config validation (see `self-diagnostics`) | +| `netclaw status` | Runtime health from daemon endpoint | + +### Configuration + +| Command | Purpose | +|---------|---------| +| `netclaw init` | First-run setup wizard | +| `netclaw provider` | Manage LLM providers (TUI or subcommands: `add`, `auth`, `list`, `get`, `remove`, `enable`, `disable`) | +| `netclaw model` | Manage model assignments (TUI or subcommands) | +| `netclaw mcp` | Manage MCP servers (`add`, `auth`, `list`, `get`, `remove`, `enable`, `disable`) | +| `netclaw secrets` | Manage encrypted secrets | + +### Reminders + +| Command | Purpose | +|---------|---------| +| `netclaw reminder list` | List all reminders | +| `netclaw reminder create` | Create a reminder | +| `netclaw reminder show ` | Show reminder details | +| `netclaw reminder cancel ` | Delete a reminder | +| `netclaw reminder enable ` | Enable a disabled reminder | +| `netclaw reminder disable ` | Disable a reminder | +| `netclaw reminder import ` | Import reminders from file | +| `netclaw reminder validate ` | Validate reminder file without importing | +| `netclaw reminder ui` | Reminder creation TUI | + +### Maintenance + +| Command | Purpose | +|---------|---------| +| `netclaw update` | Check for and install updates | +| `netclaw --version` | Show CLI version | + +## Health Endpoints + +| Endpoint | Purpose | +|----------|---------| +| `http://127.0.0.1:5199/api/health/ready` | Readiness probe | +| `http://127.0.0.1:5199/api/health/status` | Full runtime status JSON | +| `http://127.0.0.1:5199/api/sessions` | Active session list | + +## Cross-References + +- Memory tool usage: read `memory-usage` +- Memorizer MCP operations: read `memorizer-usage` +- Troubleshooting and diagnostics: read `self-diagnostics` +- Identity file management: read `identity-management` +- Creating new skills: read `skill-authoring` +- Search behavior and citation policy: read `search-citation` diff --git a/feeds/skills/.system/files/search-citation/1.0.0/SKILL.md b/feeds/skills/.system/files/search-citation/1.0.0/SKILL.md new file mode 100644 index 000000000..feed8aa5e --- /dev/null +++ b/feeds/skills/.system/files/search-citation/1.0.0/SKILL.md @@ -0,0 +1,86 @@ +--- +name: search-citation +description: "Guides when to use web search vs. training data and how to cite sources. Ensures specific factual claims include source URLs and the agent does not hallucinate verifiable information." +metadata: + author: netclaw + version: "1.0.0" + triggers: web search needed | cite sources | link results | price check | product search | find near me | verify facts +--- + +## When to Search + +Use `web_search` when the answer is specific, time-sensitive, or verifiable: + +- Prices, availability, current stock +- Current events, news, recent happenings +- Specific product info, specs, reviews +- Local businesses, restaurants, services +- Travel options (flights, hotels, bookings) +- Anything where being wrong has consequences or the data changes + +## When Training Data Is Fine + +Do not search for things that are general, stable, or conceptual: + +- How things work, science, definitions +- Well-established facts that do not change +- Programming concepts, math, language questions +- Opinion or advice where your reasoning is the value +- General heuristics ("mid-week flights are usually cheaper") — these are fine + as a first response before offering to search for specifics + +## Use Context to Refine Searches + +Your context may include user preferences relevant to the search — location, +preferred vendors, dietary needs, budget, loyalty programs, etc. Use these to +refine queries rather than asking the user to restate them. + +- Mention the preference used so the user can correct if needed + ("checking United since that's your preferred airline") +- See reference files for which preferences apply to each search type: + - `references/local-search.md` — restaurants, bars, shops, services + - `references/travel-search.md` — flights, hotels, bookings + - `references/product-search.md` — products, hardware, goods + +**Example flow:** + +1. User asks about flights +2. Offer general advice from training data ("mid-week is usually cheapest") +3. Offer to search for specifics +4. When searching, use context-provided preferences (preferred airline, home + airport) to tailor the query + +## Citation Rules + +Every specific factual claim from a search **must** include a source URL. + +| Rule | Detail | +|------|--------| +| Cite every claim | If the information came from a search result, link it | +| Link all sources | When multiple sources found, link all of them — recommend one if you have a basis | +| Prefer specific pages | Link to the product page, restaurant page, or listing — not to a search results or category page | +| No URL, no fact | Do not present specific claims (prices, ratings, availability) without a source URL | +| Unlinkable content | If a source cannot be linked directly (form-post navigation, JS-rendered content), use browser automation to capture a screenshot and attach it via `attach_file` — a screenshot beats no source | + +## When Search Is Not Available + +If the `web` grant is not enabled and the query requires a search: + +- Tell the user they need to enable web search for this type of query +- Do not fall back to training data for something that should be searched +- Do not guess at prices, availability, or other verifiable specifics + +## When Search Comes Up Empty + +If a search returns no useful results: + +- Say so honestly: "I wasn't able to find current information on X" +- Do not guess or fabricate specifics to fill the gap +- Offer alternative approaches if possible (different search terms, checking + a specific site with `web_fetch`, trying later) + +## Cross-References + +- Tool catalog and grant system: read `capability-reference` +- Memory patterns and recall: read `memory-usage` +- Search-type-specific guidance: see `references/` files listed above diff --git a/feeds/skills/.system/files/search-citation/1.0.0/references/local-search.md b/feeds/skills/.system/files/search-citation/1.0.0/references/local-search.md new file mode 100644 index 000000000..dccc2b8ad --- /dev/null +++ b/feeds/skills/.system/files/search-citation/1.0.0/references/local-search.md @@ -0,0 +1,41 @@ +# Local Search: Restaurants, Bars, Shops, Services + +Guidance for searching businesses and services near a specific location. + +## Context Preferences + +Use these if available in your context — do not ask the user to restate them: + +| Preference | How to use | +|------------|------------| +| Home location | Default for "near me" queries — only ask if nothing is available and it cannot be inferred | +| Dietary restrictions | Filter restaurant results (vegetarian, gluten-free, allergies) | +| Cuisine preferences | Prioritize matching cuisines when suggesting restaurants | +| Budget | Filter by price range | + +## What to Include + +For each result, include as much of the following as the search provides: + +- Business name +- Address or neighborhood +- Hours of operation (note if these may vary on holidays or seasonally) +- Phone number +- Price range or price tier (for restaurants: $, $$, $$$) +- Cuisine type (for restaurants) + +## Linking Rules + +- Link to the business's own website or Google Maps listing +- Do not link to aggregator search result pages (e.g., Yelp search results) +- A direct Google Maps link or the business's own site lets the user see + location, reviews, and hours in one place +- If multiple businesses are suggested, each one gets its own link + +## Tips + +- If the user says "near me" and no location is in context, ask once — then + suggest storing it for future queries +- Note when hours or seasonal availability might affect the recommendation +- When comparing options, a brief structured list (name, distance, price tier, + cuisine) helps the user scan quickly diff --git a/feeds/skills/.system/files/search-citation/1.0.0/references/product-search.md b/feeds/skills/.system/files/search-citation/1.0.0/references/product-search.md new file mode 100644 index 000000000..b6a09e831 --- /dev/null +++ b/feeds/skills/.system/files/search-citation/1.0.0/references/product-search.md @@ -0,0 +1,47 @@ +# Product Search: Shopping, Hardware, Goods + +Guidance for searching products, comparing prices, and finding specific items. + +## Context Preferences + +Use these if available in your context — do not ask the user to restate them: + +| Preference | How to use | +|------------|------------| +| Budget | Filter or sort by price range | +| Preferred retailers | Prioritize results from those stores | +| Brand preferences | Narrow search to preferred brands when relevant | + +## What to Include + +For each product result: + +- Product name and key specs +- Price and retailer +- Link to the specific product page + +When comparing products, present in a structured format: + +| Product | Price | Retailer | Key Specs | +|---------|-------|----------|-----------| +| Example | $X.XX | Store | Specs here | + +## Linking Rules + +- Link to the specific product page, not to search results or category pages +- A direct product page URL triggers rich previews (image, title, price) in + most chat clients — this is far more useful than a generic search link +- If the same product is available from multiple retailers, link each one so + the user can compare +- Prefer retailer product pages over review aggregator pages — let the user + see the actual price and availability + +## Important Caveats + +- Note if prices may vary (marketplace/third-party sellers, regional pricing) +- Note if an item is sold by a third-party seller on a marketplace (e.g., + Amazon third-party vs. sold by Amazon) +- If stock or availability is uncertain, say so rather than implying it is + in stock +- When the user asks for "cheap" options, search broadly — do not limit to + one retailer diff --git a/feeds/skills/.system/files/search-citation/1.0.0/references/travel-search.md b/feeds/skills/.system/files/search-citation/1.0.0/references/travel-search.md new file mode 100644 index 000000000..30e095c76 --- /dev/null +++ b/feeds/skills/.system/files/search-citation/1.0.0/references/travel-search.md @@ -0,0 +1,46 @@ +# Travel Search: Flights, Hotels, Bookings + +Guidance for searching flights, hotels, and travel-related bookings. + +## Context Preferences + +Use these if available in your context — do not ask the user to restate them: + +| Preference | How to use | +|------------|------------| +| Home airport | Default departure city | +| Preferred airline | Search that airline first or prioritize its results | +| Loyalty programs | Note when results earn miles/points in a program the user belongs to | +| Travel budget | Filter or sort by price range | + +## What to Include + +### Flights + +- Airline and flight number (if available) +- Departure and arrival times with time zones +- Number of stops (nonstop, 1 stop, etc.) +- Price per person +- Link to the booking or listing page + +### Hotels + +- Hotel name and neighborhood/location +- Price per night +- Star rating or review score +- Key amenities (breakfast, parking, Wi-Fi) +- Link to the booking or listing page + +## Linking Rules + +- Link to specific booking or listing pages, not search result pages +- If comparing across providers (airline site vs. aggregator), link to each +- A direct booking link saves the user from re-searching + +## Important Caveats + +- Prices change frequently — note when the results were found + ("as of [date/time]") so the user knows the information may already be stale +- Suggest the user verify the price before booking +- If the search returns a wide price range, present a few representative + options (cheapest, best value, most convenient) rather than an exhaustive list diff --git a/feeds/skills/.system/manifest.json b/feeds/skills/.system/manifest.json index af2a5ea4c..fa6cd004e 100644 --- a/feeds/skills/.system/manifest.json +++ b/feeds/skills/.system/manifest.json @@ -1,15 +1,15 @@ { "schemaVersion": 1, "feedType": "system", - "updatedAt": "2026-03-13T19:58:13Z", + "updatedAt": "2026-03-13T20:48:06Z", "skills": [ { "name": "capability-reference", - "version": "1.0.0", + "version": "1.1.0", "minimumDaemonVersion": "0.1.0", - "sha256": "7a0c2e1c40fb9dd5360eb6f8e25643d154bb2775964d906a3add6e5166ac92b6", - "sizeBytes": 6208, - "url": "https://feeds.netclaw.dev/skills/.system/files/capability-reference/1.0.0/SKILL.md", + "sha256": "235de715ffed23c32c196b2f4da6e22d7fe01fe2636bf9e608bf55083f3f1f85", + "sizeBytes": 6270, + "url": "https://feeds.netclaw.dev/skills/.system/files/capability-reference/1.1.0/SKILL.md", "category": null, "description": "Quick-lookup catalog of all built-in tools, CLI commands, tool grant categories, scheduling syntax, and MCP discovery. Read when unsure what tools or commands are available." }, @@ -43,6 +43,36 @@ "category": null, "description": "How SQLite-backed memory now splits automatic durable recall from intentional evidence search" }, + { + "name": "search-citation", + "version": "1.0.0", + "minimumDaemonVersion": "0.1.0", + "sha256": "e26d4ae5d9554df04d6238886b564b74b3f8b8ba13ec858a9ea787f32775b062", + "sizeBytes": 3718, + "url": "https://feeds.netclaw.dev/skills/.system/files/search-citation/1.0.0/SKILL.md", + "category": null, + "description": "Guides when to use web search vs. training data and how to cite sources. Ensures specific factual claims include source URLs and the agent does not hallucinate verifiable information.", + "files": [ + { + "path": "references/local-search.md", + "sha256": "a913d2efdfd546ef85d24116ae3ad2a621f422c885f79751a7c465072b72dda2", + "sizeBytes": 1584, + "url": "https://feeds.netclaw.dev/skills/.system/files/search-citation/1.0.0/references/local-search.md" + }, + { + "path": "references/product-search.md", + "sha256": "e89a691b5209e235fd9e8ae5f76cb4a7a1bb5d9a96dcbe454077ad01ee56d2b4", + "sizeBytes": 1642, + "url": "https://feeds.netclaw.dev/skills/.system/files/search-citation/1.0.0/references/product-search.md" + }, + { + "path": "references/travel-search.md", + "sha256": "b1b3eba5ecb374d8f14e7340c46c3c4c33e4f68767fc1a9a0ef30662d04144dc", + "sizeBytes": 1531, + "url": "https://feeds.netclaw.dev/skills/.system/files/search-citation/1.0.0/references/travel-search.md" + } + ] + }, { "name": "self-diagnostics", "version": "1.2.0", diff --git a/src/Netclaw.Daemon/BuiltInSkills/capability-reference.md b/src/Netclaw.Daemon/BuiltInSkills/capability-reference.md index b6997e700..1cb768290 100644 --- a/src/Netclaw.Daemon/BuiltInSkills/capability-reference.md +++ b/src/Netclaw.Daemon/BuiltInSkills/capability-reference.md @@ -3,7 +3,7 @@ name: capability-reference description: "Quick-lookup catalog of all built-in tools, CLI commands, tool grant categories, scheduling syntax, and MCP discovery. Read when unsure what tools or commands are available." metadata: author: netclaw - version: "1.0.0" + version: "1.1.0" triggers: what can I do | available tools | CLI commands | how to schedule | tool grants | MCP discovery | list capabilities --- @@ -174,3 +174,4 @@ scheduled work back to the originating conversation. - Troubleshooting and diagnostics: read `self-diagnostics` - Identity file management: read `identity-management` - Creating new skills: read `skill-authoring` +- Search behavior and citation policy: read `search-citation` diff --git a/src/Netclaw.Daemon/BuiltInSkills/search-citation.md b/src/Netclaw.Daemon/BuiltInSkills/search-citation.md new file mode 100644 index 000000000..feed8aa5e --- /dev/null +++ b/src/Netclaw.Daemon/BuiltInSkills/search-citation.md @@ -0,0 +1,86 @@ +--- +name: search-citation +description: "Guides when to use web search vs. training data and how to cite sources. Ensures specific factual claims include source URLs and the agent does not hallucinate verifiable information." +metadata: + author: netclaw + version: "1.0.0" + triggers: web search needed | cite sources | link results | price check | product search | find near me | verify facts +--- + +## When to Search + +Use `web_search` when the answer is specific, time-sensitive, or verifiable: + +- Prices, availability, current stock +- Current events, news, recent happenings +- Specific product info, specs, reviews +- Local businesses, restaurants, services +- Travel options (flights, hotels, bookings) +- Anything where being wrong has consequences or the data changes + +## When Training Data Is Fine + +Do not search for things that are general, stable, or conceptual: + +- How things work, science, definitions +- Well-established facts that do not change +- Programming concepts, math, language questions +- Opinion or advice where your reasoning is the value +- General heuristics ("mid-week flights are usually cheaper") — these are fine + as a first response before offering to search for specifics + +## Use Context to Refine Searches + +Your context may include user preferences relevant to the search — location, +preferred vendors, dietary needs, budget, loyalty programs, etc. Use these to +refine queries rather than asking the user to restate them. + +- Mention the preference used so the user can correct if needed + ("checking United since that's your preferred airline") +- See reference files for which preferences apply to each search type: + - `references/local-search.md` — restaurants, bars, shops, services + - `references/travel-search.md` — flights, hotels, bookings + - `references/product-search.md` — products, hardware, goods + +**Example flow:** + +1. User asks about flights +2. Offer general advice from training data ("mid-week is usually cheapest") +3. Offer to search for specifics +4. When searching, use context-provided preferences (preferred airline, home + airport) to tailor the query + +## Citation Rules + +Every specific factual claim from a search **must** include a source URL. + +| Rule | Detail | +|------|--------| +| Cite every claim | If the information came from a search result, link it | +| Link all sources | When multiple sources found, link all of them — recommend one if you have a basis | +| Prefer specific pages | Link to the product page, restaurant page, or listing — not to a search results or category page | +| No URL, no fact | Do not present specific claims (prices, ratings, availability) without a source URL | +| Unlinkable content | If a source cannot be linked directly (form-post navigation, JS-rendered content), use browser automation to capture a screenshot and attach it via `attach_file` — a screenshot beats no source | + +## When Search Is Not Available + +If the `web` grant is not enabled and the query requires a search: + +- Tell the user they need to enable web search for this type of query +- Do not fall back to training data for something that should be searched +- Do not guess at prices, availability, or other verifiable specifics + +## When Search Comes Up Empty + +If a search returns no useful results: + +- Say so honestly: "I wasn't able to find current information on X" +- Do not guess or fabricate specifics to fill the gap +- Offer alternative approaches if possible (different search terms, checking + a specific site with `web_fetch`, trying later) + +## Cross-References + +- Tool catalog and grant system: read `capability-reference` +- Memory patterns and recall: read `memory-usage` +- Search-type-specific guidance: see `references/` files listed above