diff --git a/nanobot/skills/README.md b/nanobot/skills/README.md index 19cf24579..22e472ead 100644 --- a/nanobot/skills/README.md +++ b/nanobot/skills/README.md @@ -9,10 +9,10 @@ Each skill is a directory containing a `SKILL.md` file with: - Markdown instructions for the agent When skills reference large local documentation or logs, prefer nanobot's built-in -`grep` / `glob` tools to narrow the search space before loading full files. +`grep` tool to narrow the search space before loading full files. Use `grep(output_mode="count")` / `files_with_matches` for broad searches first, use `head_limit` / `offset` to page through large result sets, -and `glob(entry_type="dirs")` when discovering directory structure matters. +and `grep(glob="*.md")` to filter by file name pattern. ## Attribution diff --git a/nanobot/skills/skill-creator/SKILL.md b/nanobot/skills/skill-creator/SKILL.md index a3f2d6477..c9c71d4e0 100644 --- a/nanobot/skills/skill-creator/SKILL.md +++ b/nanobot/skills/skill-creator/SKILL.md @@ -86,7 +86,7 @@ Documentation and reference material intended to be loaded as needed into contex - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides - **Benefits**: Keeps SKILL.md lean, loaded only when the agent determines it's needed -- **Best practice**: If files are large (>10k words), include grep or glob patterns in SKILL.md so the agent can use built-in search tools efficiently; mention when the default `grep(output_mode="files_with_matches")`, `grep(output_mode="count")`, `grep(fixed_strings=true)`, `glob(entry_type="dirs")`, or pagination via `head_limit` / `offset` is the right first step +- **Best practice**: If files are large (>10k words), include grep patterns in SKILL.md so the agent can use built-in search tools efficiently; mention when the default `grep(output_mode="files_with_matches")`, `grep(output_mode="count")`, `grep(fixed_strings=true)`, or pagination via `head_limit` / `offset` is the right first step - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. ##### Assets (`assets/`) diff --git a/nanobot/templates/TOOLS.md b/nanobot/templates/TOOLS.md index 7543f5839..374e49778 100644 --- a/nanobot/templates/TOOLS.md +++ b/nanobot/templates/TOOLS.md @@ -10,19 +10,11 @@ This file documents non-obvious constraints and usage patterns. - Output is truncated at 10,000 characters - `restrictToWorkspace` config can limit file access to the workspace -## glob — File Discovery - -- Use `glob` to find files by pattern before falling back to shell commands -- Simple patterns like `*.py` match recursively by filename -- Use `entry_type="dirs"` when you need matching directories instead of files -- Use `head_limit` and `offset` to page through large result sets -- Prefer this over `exec` when you only need file paths - ## grep — Content Search - Use `grep` to search file contents inside the workspace - Default behavior returns only matching file paths (`output_mode="files_with_matches"`) -- Supports optional `glob` filtering plus `context_before` / `context_after` +- Supports optional `glob` filtering (e.g. `glob="*.py"`) plus `context_before` / `context_after` - Supports `type="py"`, `type="ts"`, `type="md"` and similar shorthand filters - Use `fixed_strings=true` for literal keywords containing regex characters - Use `output_mode="files_with_matches"` to get only matching file paths diff --git a/nanobot/templates/agent/identity.md b/nanobot/templates/agent/identity.md index 6602f7fe9..6548c1def 100644 --- a/nanobot/templates/agent/identity.md +++ b/nanobot/templates/agent/identity.md @@ -24,7 +24,7 @@ Output is rendered in a terminal. Avoid markdown headings and tables. Use plain ## Search & Discovery -- Prefer built-in `grep` / `glob` over `exec` for workspace search. +- Prefer built-in `grep` over `exec` for workspace search. - On broad searches, use `grep(output_mode="count")` to scope before requesting full content. {% include 'agent/_snippets/untrusted_content.md' %}