docs: fix inaccuracies in custom tools and skills documentation

docs/features/experimental/custom-tools.md

@@ -59,7 +59,7 @@ export default defineCustomTool({
 - **`parameters`**: Zod schema converted to JSON Schema for validation
 - **`execute`**: Async function returning a string result to Roo
 
-Tools are dynamically loaded and transpiled with esbuild. Changes to tool files trigger automatic reload.
+Tools are dynamically loaded and transpiled with esbuild. Automatic reload on file changes isn't reliable—use the **Refresh Custom Tools** command to pick up changes immediately.
 
 ---
 
@@ -118,15 +118,15 @@ export default defineCustomTool({
 
 ## Per-Tool Environment Variables
 
-Tools automatically load a `.env` file from the same folder. This lets you store API keys and secrets without hardcoding them.
+Roo copies `.env` and `.env.*` files from your tool directory into the tool's cache folder so your tool can load them at runtime. **Roo does not automatically inject these variables into `process.env`**—your tool must load them itself.
 
 **Setup:**
 
 1. Create a `.env` file next to your tool:
    ```
    .roo/tools/
    ├── my-tool.ts
-   ├── .env          # Loaded automatically
+   ├── .env          # Copied to cache dir at load time
    └── package.json
    ```
 
@@ -137,9 +137,14 @@ Tools automatically load a `.env` file from the same folder. This lets you store
    API_SECRET=your-secret-key
    ```
 
-3. Access them via `process.env`:
+3. Load the `.env` in your tool using `dotenv` and `__dirname`:
    ```typescript
    import { parametersSchema as z, defineCustomTool } from "@roo-code/types"
+   import dotenv from "dotenv"
+   import path from "path"
+
+   // Load .env from the tool's cache directory
+   dotenv.config({ path: path.join(__dirname, ".env") })
 
    export default defineCustomTool({
      name: "notify_slack",
@@ -164,6 +169,8 @@ Tools automatically load a `.env` file from the same folder. This lets you store
    })
    ```
 
+**Why `__dirname`?** Roo copies your `.env` files into a cache directory alongside the transpiled tool. Using `__dirname` ensures your tool finds the `.env` in the correct location regardless of where the tool was originally defined.
+
 **Security:** Ensure your `.env` file is ignored by version control to keep secrets safe.
 
 ---

docs/features/skills.mdx

@@ -56,11 +56,11 @@ You can't package bundled assets (scripts, templates, references) with custom in
 
 Skills use **progressive disclosure** to efficiently load content only when needed:
 
-**Level 1: Discovery** - Roo always knows which skills are available by reading their `name` and `description` from frontmatter. This lightweight metadata helps Roo decide which skills match your request.
+**Level 1: Discovery** - Roo reads each `SKILL.md` file and parses its frontmatter to extract `name` and `description`. Only this metadata is stored for matching—the full content isn't held in memory until needed.
 
 **Level 2: Instructions** - When your request matches a skill's description, Roo uses [`read_file`](/advanced-usage/available-tools/read-file) to load the full SKILL.md instructions into context.
 
-**Level 3: Resources** - Roo accesses additional skill files (scripts, templates, references) only as needed during execution.
+**Level 3: Resources** - The prompt tells Roo it may access bundled files (scripts, templates, references) alongside the skill. There's no separate resource manifest—Roo discovers these files on-demand when the instructions reference them.
 
 This architecture means skills remain dormant until activated—they don't bloat your base prompt. You can install many skills, and Roo loads only what's relevant for each task.
 
@@ -123,9 +123,12 @@ When the user requests PDF processing:
 - Large files: Suggest page-by-page processing
 ```
 
-**Critical rules:**
-- The `name` field must exactly match the directory name
+**Naming rules:**
+- The `name` field must exactly match the directory name (or symlink name)
+- Names must be 1–64 characters, lowercase letters/numbers/hyphens only
+- No leading/trailing hyphens, no consecutive hyphens (e.g., `my--skill` is invalid)
 - Both `name` and `description` are required
+- Descriptions must be 1–1024 characters (trimmed)
 - The description tells Roo when to use this skill—be specific
 
 #### 4. Test the skill
@@ -183,42 +186,45 @@ Create skills that only activate in specific modes:
 
 ## Override Priority
 
-When skills with the same name exist in multiple locations, this priority applies:
+When skills with the same name exist in multiple locations, this priority applies (project vs global is evaluated first, then mode-specific vs generic within each source):
 
 1. **Project mode-specific** (`.roo/skills-code/my-skill/`)
-2. **Global mode-specific** (`~/.roo/skills-code/my-skill/`)
-3. **Project generic** (`.roo/skills/my-skill/`)
+2. **Project generic** (`.roo/skills/my-skill/`)
+3. **Global mode-specific** (`~/.roo/skills-code/my-skill/`)
 4. **Global generic** (`~/.roo/skills/my-skill/`)
 
+This means a **project generic** skill overrides a **global mode-specific** skill—project location takes precedence over mode specificity.
+
 This lets you:
 - Set global standards that work everywhere
-- Override them per-project when needed
-- Specialize skills for specific modes
+- Override them per-project when needed (even with generic skills)
+- Specialize skills for specific modes within each location
 
 ---
 
 ## Skill Discovery
 
 Roo automatically discovers skills:
-- **At startup**: All skills are indexed
+- **At startup**: All skills are indexed by reading and parsing each SKILL.md
 - **During development**: File watchers detect changes to SKILL.md files
 - **Mode filtering**: Only skills relevant to the current mode are available
 
 You don't need to register or configure skills—just create the directory structure.
 
+:::warning Custom System Prompts Override Skills
+If you have a file-based custom system prompt (`.roo/system-prompt-{mode-slug}`), it replaces the standard system prompt entirely—including the skills section. Skills won't be available when a custom system prompt is active.
+:::
+
 #### Symlink support
 
-Skills support symbolic links for sharing:
+Skills support symbolic links for sharing skill libraries across projects:
 
 ```bash
 # Share a skill library across projects
 ln -s /shared/company-skills ~/.roo/skills/company-standards
-
-# Use different names for the same skill
-ln -s ~/.roo/skills/pdf-processing ~/.roo/skills/pdf-handler
 ```
 
-The skill name comes from the symlink name (or directory name if not symlinked). The frontmatter `name` field must still match this name.
+The skill name comes from the symlink name (or directory name if not symlinked). The frontmatter `name` field must match this name exactly—you can't create aliases with different names pointing to the same skill.
 
 ---
 
@@ -307,24 +313,20 @@ The skill name comes from the symlink name (or directory name if not symlinked).
 
 ## Skill Specification
 
-Roo Code skills follow the [Agent Skills](https://agentskills.io/) open standard for skill packaging and metadata. This means skills you create are **portable across Agent Skills-compatible tools**, including:
+Roo Code skills follow the [Agent Skills](https://agentskills.io/) format for skill packaging and metadata. Skills are **instruction packages with optional bundled files**—they don't register new executable tools.
 
-- **Roo Code** - Available in all modes with automatic discovery
-- **GitHub Copilot** (VS Code) - Works in chat and coding agent
-- **OpenAI Codex** - Accessible in CLI and IDE extensions
-- **Other compatible agents** - Any tool implementing the Agent Skills standard
+**Required conventions:**
+- The frontmatter `name` must exactly match the directory (or symlink) name
+- Both `name` and `description` fields are required in frontmatter
+- Names: 1–64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens
+- Descriptions: 1–1024 chars (trimmed)
 
 #### Roo-specific enhancements
 
-While maintaining compatibility with the core standard, Roo Code adds mode-specific targeting:
-
-- **Standard locations**: `.roo/skills/` and `~/.roo/skills/` work with any Agent Skills-compatible tool
-- **Mode-specific directories**: `skills-{mode}/` (e.g., `skills-code/`, `skills-architect/`) are Roo enhancements that enable mode targeting without affecting portability—other tools will simply ignore these directories
+Roo Code adds mode-specific targeting beyond the base format:
 
-This means you can:
-- Share generic skills across different AI tools
-- Use mode-specific optimizations when working in Roo Code
-- Maintain a single skill library that works everywhere
+- **Standard locations**: `.roo/skills/` and `~/.roo/skills/`
+- **Mode-specific directories**: `skills-{mode}/` (e.g., `skills-code/`, `skills-architect/`) enable mode targeting
 
 ---