Skip to content

feat(skills): add search-citation skill for web search guidance #219

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Aaronontheweb merged 1 commit into from
Mar 13, 2026
Merged

feat(skills): add search-citation skill for web search guidance #219

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
177 changes: 177 additions & 0 deletions feeds/skills/.system/files/capability-reference/1.1.0/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/<server>.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 <id>` | 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 <id>` | Show reminder details |
| `netclaw reminder cancel <id>` | Delete a reminder |
| `netclaw reminder enable <id>` | Enable a disabled reminder |
| `netclaw reminder disable <id>` | Disable a reminder |
| `netclaw reminder import <file>` | Import reminders from file |
| `netclaw reminder validate <file>` | 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`
86 changes: 86 additions & 0 deletions feeds/skills/.system/files/search-citation/1.0.0/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
41 changes: 41 additions & 0 deletions feeds/skills/.system/files/search-citation/1.0.0/references/local-search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
47 changes: 47 additions & 0 deletions feeds/skills/.system/files/search-citation/1.0.0/references/product-search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading
Loading