@diffexai/diffex 0.2.4 → 0.2.5

package/docs/settings.md

@@ -1,341 +0,0 @@
-# Settings
-
-Diffex uses JSON settings files with project settings overriding global settings.
-
-| Location | Scope |
-|----------|-------|
-| `~/.diffex/agent/settings.json` | Global (all projects) |
-| `.diffex/settings.json` | Project (current directory) |
-
-Edit directly or use `/settings` for common options.
-
-## Project Trust
-
-On interactive startup, Diffex asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` and has no saved decision for the folder or a parent folder in `~/.diffex/agent/trust.json`. Trusting a project allows Diffex to load `.diffex/settings.json` and `.diffex` resources, install missing project packages, and execute project extensions.
-
-Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
-
-If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.diffex/agent/settings.json`, or change it with `/settings`.
-
-`diffex config` and package commands use the same project trust flow, except `diffex update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
-
-Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.diffex/agent/trust.json` only; the current session is not reloaded, so restart Diffex for changes to take effect.
-
-## All Settings
-
-### Model & Thinking
-
-Use `/model` or Ctrl+L to select a model, then choose from its supported thinking levels. Exact `/model <id>` matches and selecting the current model also open this screen. It is skipped when there is at most one supported level. Escape or Ctrl+C keeps the selected model and its current supported level. The thinking preference is shared across models and saved as `defaultThinkingLevel`, with existing model capability clamping.
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `defaultProvider` | string | - | Default provider (e.g., `"anthropic"`, `"openai"`) |
-| `defaultModel` | string | - | Default model ID |
-| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` |
-| `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
-| `showCacheMissNotices` | boolean | `false` | Show transcript notices for significant prompt-cache misses |
-| `thinkingBudgets` | object | - | Custom token budgets per thinking level |
-
-#### thinkingBudgets
-
-```json
-{
-  "thinkingBudgets": {
-    "minimal": 1024,
-    "low": 4096,
-    "medium": 10240,
-    "high": 32768
-  }
-}
-```
-
-### UI & Display
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, or custom) |
-| `externalEditor` | string | `$VISUAL`, then `$EDITOR`, then Notepad on Windows or `nano` elsewhere | Command for Ctrl+G external editor; takes precedence over environment variables |
-| `quietStartup` | boolean | `false` | Hide startup header |
-| `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
-| `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
-| `enableProviderAttribution` | boolean | `false` | Add optional attribution headers to OpenRouter, Cloudflare, and direct NVIDIA NIM requests |
-| `enableAnalytics` | boolean | `false` | Opt-in analytics data sharing. Currently only asked for during the experimental first-time setup (`DIFFEX_EXPERIMENTAL=1`) |
-| `trackingId` | string | - | Analytics tracking identifier, generated when `enableAnalytics` is turned on |
-| `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
-| `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
-| `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |
-| `outputPad` | number | `1` | Horizontal padding for user messages, assistant messages, and thinking (0 or 1) |
-| `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
-| `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
-| `tuiMode` | string | `"regular"` | Interactive TUI mode: `"regular"` or experimental `"fullscreen"`. Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
-| `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling, `"always"` reserves the rightmost column and keeps it visible, and `"hidden"` hides it. Has no effect in regular TUI mode |
-
-For VS Code, include `--wait` so Diffex resumes after the editor exits:
-
-```json
-{
-  "externalEditor": "code --wait"
-}
-```
-
-### Provider attribution and update checks
-
-Diffex does not send install or update telemetry reports.
-The former `enableInstallTelemetry` setting and `DIFFEX_TELEMETRY` variable are ignored.
-Optional provider attribution defaults off so removing the old shared setting cannot re-enable headers for users who previously opted out.
-Use `enableProviderAttribution` or `DIFFEX_PROVIDER_ATTRIBUTION` to control optional OpenRouter, Cloudflare, and direct NVIDIA NIM headers independently.
-The environment variable takes precedence: `1`/`true`/`yes` enables attribution; `0`/`false`/`no` disables it.
-This setting does not control update checks, OpenCode session headers, or explicitly configured request headers.
-
-Set `DIFFEX_SKIP_VERSION_CHECK=1` to disable automatic release checks against `https://api.diffex.ai/api/latest-version`.
-Use `--offline` or `DIFFEX_OFFLINE=1` to disable startup network operations, including update checks and package update checks.
-
-### Network
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `httpProxy` | string | - | HTTP proxy URL applied as `HTTP_PROXY` and `HTTPS_PROXY`. Global setting only. |
-
-```json
-{
-  "httpProxy": "http://127.0.0.1:7890"
-}
-```
-
-### Warnings
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `warnings.anthropicExtraUsage` | boolean | `true` | Show a warning when Anthropic subscription auth may use paid extra usage |
-
-```json
-{
-  "warnings": {
-    "anthropicExtraUsage": false
-  }
-}
-```
-
-### Evolution
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `evolution.enabled` | boolean | `true` | Global-only. Enables future invocation tracing and manual/background evolution controls. Disabling it does not unselect the active harness or remove active evolved skills. |
-
-Already-running Diffex processes monitor this setting. A change made by another process is applied to their trace collectors and evolution workers without a restart.
-
-Automatic work requires at least 400,000 provider-reported input and output tokens from unprocessed assistant messages, at least three eligible settled invocations, and a 10-minute cooldown after the previous automatic run. Each automatic run processes the oldest unprocessed evidence through the complete invocation that reaches or crosses the same 400,000-token trigger threshold. Only that final invocation may take the batch over the threshold; later invocations stay queued. Larger backlogs continue in threshold-sized batches after each cooldown, while partial batches wait for the threshold. Manual runs remain uncapped. The token total matches the response usage counter and excludes cache-read and cache-write usage. Evolution model calls may consume provider quota. See [Harness Evolution](evolution.md).
-
-### Compaction
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `compaction.enabled` | boolean | `true` | Enable auto-compaction |
-| `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
-| `compaction.keepRecentTokens` | number | `20000` | Recent tokens to keep (not summarized) |
-
-```json
-{
-  "compaction": {
-    "enabled": true,
-    "reserveTokens": 16384,
-    "keepRecentTokens": 20000
-  }
-}
-```
-
-### Branch Summary
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `branchSummary.reserveTokens` | number | `16384` | Tokens reserved for branch summarization |
-| `branchSummary.skipPrompt` | boolean | `false` | Skip "Summarize branch?" prompt on `/tree` navigation (defaults to no summary) |
-
-### Retry
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `retry.enabled` | boolean | `true` | Enable automatic agent-level retry on transient errors |
-| `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts |
-| `retry.baseDelayMs` | number | `2000` | Base delay for agent-level exponential backoff (2s, 4s, 8s) |
-| `retry.provider.timeoutMs` | number | SDK default | Provider/SDK request timeout in milliseconds |
-| `retry.provider.maxRetries` | number | `0` | Provider/SDK retry attempts |
-| `retry.provider.maxRetryDelayMs` | number | `60000` | Max server-requested delay before failing (60s) |
-
-When a provider requests a retry delay longer than `retry.provider.maxRetryDelayMs`, the request fails immediately with an informative error instead of waiting silently. Set it to `0` to disable the limit.
-
-Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explicitly needed. Setting it above `0` can make SDK/provider retries handle out-of-usage-limit errors before Diffex sees them, which may block the agent until the provider quota resets in some circumstances.
-
-```json
-{
-  "retry": {
-    "enabled": true,
-    "maxRetries": 3,
-    "baseDelayMs": 2000,
-    "provider": {
-      "timeoutMs": 3600000,
-      "maxRetries": 0,
-      "maxRetryDelayMs": 60000
-    }
-  }
-}
-```
-
-### Message Delivery
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `steeringMode` | string | `"one-at-a-time"` | How steering messages are sent: `"all"` or `"one-at-a-time"` |
-| `followUpMode` | string | `"one-at-a-time"` | How follow-up messages are sent: `"all"` or `"one-at-a-time"` |
-| `transport` | string | `"auto"` | Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, `"websocket-cached"`, or `"auto"` |
-| `httpIdleTimeoutMs` | number | `300000` | HTTP header/body idle timeout in milliseconds, also used by providers with explicit stream idle timeouts. Set to `0` to disable. |
-| `websocketConnectTimeoutMs` | number | `15000` | WebSocket connect/open handshake timeout in milliseconds for providers that support WebSocket transports. Set to `0` to disable. |
-
-### Terminal & Images
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
-| `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells |
-| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
-| `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max. Applies to `@file` attachments, `read`, and images returned by tools |
-| `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
-
-### Shell
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `shellPath` | string | - | Custom shell path (e.g., for Cygwin on Windows); supports a leading `~` for the home directory |
-| `shellCommandPrefix` | string | - | Prefix for every bash command (e.g., `"shopt -s expand_aliases"`) |
-| `npmCommand` | string[] | - | Command argv used for npm package lookup/install operations (e.g., `["mise", "exec", "node@20", "--", "npm"]`) |
-
-```json
-{
-  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
-}
-```
-
-`npmCommand` is used for all npm package-manager operations, including installs, uninstalls, and dependency installs inside git packages. User-scoped npm packages install under `~/.diffex/agent/npm/`; project-scoped npm packages install under `.diffex/npm/`. Use argv-style entries exactly as the process should be launched. When `npmCommand` is configured, git package dependency installs use plain `install` to avoid npm-specific flags in wrappers or alternate package managers.
-
-### Sessions
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `sessionDir` | string | - | Directory where session files are stored. Accepts absolute or relative paths, plus `~`. |
-
-```json
-{ "sessionDir": ".diffex/sessions" }
-```
-
-When multiple sources specify a session directory, precedence is `--session-dir`, `DIFFEX_CODING_AGENT_SESSION_DIR`, then `sessionDir` in settings.json.
-
-### Model Cycling
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `enabledModels` | string[] | - | Model patterns for Ctrl+P cycling (same format as `--models` CLI flag) |
-
-```json
-{
-  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
-}
-```
-
-### Markdown
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `markdown.codeBlockIndent` | string | `"  "` | Indentation for code blocks |
-| `markdown.mermaid` | string | `"streaming"` | Mermaid rendering mode: `"off"`, `"final"`, or `"streaming"` |
-
-### Resources
-
-These settings define where to load extensions, skills, prompts, and themes from.
-
-Use **Installed skills** in `/settings` to inspect global and workspace skill paths, sources, scopes, and enabled state. Toggle entries to persist global or project overrides, then use `/reload` to apply them to the current session. Evolved skills are read-only outside `/evolve` and `/version`.
-
-Paths in `~/.diffex/agent/settings.json` resolve relative to `~/.diffex/agent`. Paths in `.diffex/settings.json` resolve relative to `.diffex`. Absolute paths and `~` are supported.
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `packages` | array | `[]` | npm/git packages to load resources from |
-| `extensions` | string[] | `[]` | Local extension file paths or directories |
-| `skills` | string[] | `[]` | Local skill file paths or directories |
-| `prompts` | string[] | `[]` | Local prompt template paths or directories |
-| `themes` | string[] | `[]` | Local theme file paths or directories |
-
-Arrays support glob patterns and exclusions. Use `!pattern` to exclude. Use `+path` to force-include an exact path and `-path` to force-exclude an exact path.
-
-#### packages
-
-String form loads all resources from a package:
-
-```json
-{
-  "packages": ["@org/my-skills", "@org/my-extension"]
-}
-```
-
-Object form filters which resources to load:
-
-```json
-{
-  "packages": [
-    {
-      "source": "@org/my-skills",
-      "skills": ["brave-search", "transcribe"],
-      "extensions": []
-    }
-  ]
-}
-```
-
-See [packages.md](packages.md) for package management details.
-
-## Example
-
-```json
-{
-  "defaultProvider": "anthropic",
-  "defaultModel": "claude-sonnet-4-20250514",
-  "defaultThinkingLevel": "medium",
-  "theme": "dark",
-  "compaction": {
-    "enabled": true,
-    "reserveTokens": 16384,
-    "keepRecentTokens": 20000
-  },
-  "retry": {
-    "enabled": true,
-    "maxRetries": 3
-  },
-  "enabledModels": ["claude-*", "gpt-4o"],
-  "warnings": {
-    "anthropicExtraUsage": true
-  },
-  "packages": ["@org/my-skills"]
-}
-```
-
-## Project Overrides
-
-Project settings (`.diffex/settings.json`) override global settings. Nested objects are merged:
-
-```json
-// ~/.diffex/agent/settings.json (global)
-{
-  "theme": "dark",
-  "compaction": { "enabled": true, "reserveTokens": 16384 }
-}
-
-// .diffex/settings.json (project)
-{
-  "compaction": { "reserveTokens": 8192 }
-}
-
-// Result
-{
-  "theme": "dark",
-  "compaction": { "enabled": true, "reserveTokens": 8192 }
-}
-```

package/docs/shell-aliases.md

@@ -1,13 +0,0 @@
-# Shell Aliases
-
-Diffex runs bash in non-interactive mode (`bash -c`), which doesn't expand aliases by default.
-
-To enable your shell aliases, add to `~/.diffex/agent/settings.json`:
-
-```json
-{
-  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
-}
-```
-
-Adjust the path (`~/.zshrc`, `~/.bashrc`, etc.) to match your shell config.

package/docs/skills.md

@@ -1,227 +0,0 @@
-> Diffex can create skills. Ask it to build one for your use case.
-
-# Skills
-
-Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.
-
-Diffex implements the [Agent Skills standard](https://agentskills.io/specification), warning about most violations but remaining lenient. Diffex allows skill names to differ from their parent directory even though the standard disallows it; that rule is suboptimal for shared skill directories used across multiple agent harnesses.
-
-## Table of Contents
-
-- [Locations](#locations)
-- [How Skills Work](#how-skills-work)
-- [Skill Commands](#skill-commands)
-- [Skill Structure](#skill-structure)
-- [Frontmatter](#frontmatter)
-- [Validation](#validation)
-- [Example](#example)
-- [Skill Repositories](#skill-repositories)
-
-## Locations
-
-> **Security:** Skills can instruct the model to perform any action and may include executable code the model invokes. Review skill content before use.
-
-Diffex loads skills from:
-
-- Global:
-  - `~/.diffex/agent/skills/`
-  - `~/.agents/skills/`
-- Project (only after the project is trusted):
-  - `.diffex/skills/`
-  - `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
-- Packages: `skills/` directories or `diffex.skills` entries in `package.json`
-- Settings: `skills` array with files or directories
-- CLI: `--skill <path>` (repeatable, additive even with `--no-skills`)
-
-Discovery rules:
-- In `~/.diffex/agent/skills/` and `.diffex/skills/`, direct root `.md` files are discovered as individual skills
-- In all skill locations, directories containing `SKILL.md` are discovered recursively
-- In `~/.agents/skills/` and project `.agents/skills/`, root `.md` files are ignored
-
-Disable discovery with `--no-skills` (explicit `--skill` paths still load).
-
-### Using Skills from Other Harnesses
-
-To use skills from Claude Code or OpenAI Codex, add their directories to settings:
-
-```json
-{
-  "skills": [
-    "~/.claude/skills",
-    "~/.codex/skills"
-  ]
-}
-```
-
-For project-level Claude Code skills, add to `.diffex/settings.json`:
-
-```json
-{
-  "skills": ["../.claude/skills"]
-}
-```
-
-## How Skills Work
-
-1. At startup, Diffex scans skill locations and builds one catalog for the session. Each entry has a stable source identity, source kind, scope, content digest, version, and the full content captured at load time.
-2. The system prompt includes available skills in XML format per the [specification](https://agentskills.io/integrate-skills).
-3. When a task matches, the agent uses `read` to load the full SKILL.md (models don't always do this; use `/skills` to reference it explicitly).
-4. Explicit references use the catalog's captured version, so a file change does not alter a request that has already been admitted. Reload resources to catalog a changed installed skill.
-5. Invocation traces record availability, model listing, explicit references, `/skills` force-loading, and digest-matched reads as separate facts for the exact catalog version.
-6. The agent follows the instructions, using relative paths to reference scripts and assets.
-
-This is progressive disclosure: only names, descriptions, and locations are always in context; full instructions load on-demand. The TUI, system prompt, SDK, and evolution snapshots all read from the same catalog. Trace observations do not infer that a skill was used or caused an outcome.
-
-### Evolved Skills
-
-Evolved skills are immutable, workspace-scoped packages in a harness revision. The package version covers `SKILL.md` and every bundled UTF-8 supporting file, while the content digest identifies `SKILL.md` itself. Diffex exposes a package only when the active revision and workspace identity match. Selecting another revision changes `EVOLVE.md` memory and the evolved-skill set together at the next prompt boundary; in-flight and already admitted queued requests remain pinned.
-
-An evolved reference binds its skill ID, content version, digest, workspace, and harness revision. A reference from an inactive revision is rejected. `/reload` refreshes installed skills while preserving the evolved overlay from the active harness. Accepted evolved skills activate automatically after validation and any configured evaluation finish. Use `/evolve` to inspect provenance, validation, available evaluation results, activation, and rollback. See [Harness Evolution](evolution.md).
-
-## Skill Commands
-
-Use `/skills` in interactive mode to browse Installed Workspace Skills, Installed Global Skills, and Evolved Skills. Within a category, press Space to enable or disable the highlighted skill for future model prompts; enabled skills display as `[x] name` and disabled skills as `[] name`. The change applies to the next prompt. Press Enter to reference the highlighted skill in the editor without changing whether it is enabled.
-
-Referenced skills appear in the editor as purple skill-name tokens while retaining versioned references internally, so you can add the task before submitting. Each reference loads that exact captured skill content for one request, including queued steering and follow-up messages. Disabled skills remain available for explicit reference but are omitted from progressive disclosure in the system prompt.
-
-To install a package containing skills from an interactive terminal, run `diffex install <source>` and choose `Install globally` or `Install for this workspace`. The prompt shows both destinations and the trust implications. Workspace installation requires project trust and never falls back to global installation. Non-interactive installs retain the global default; pass `-l` to select workspace scope explicitly.
-
-## Skill Structure
-
-A skill is a directory with a `SKILL.md` file. Everything else is freeform.
-
-```
-my-skill/
-├── SKILL.md              # Required: frontmatter + instructions
-├── scripts/              # Helper scripts
-│   └── process.sh
-├── references/           # Detailed docs loaded on-demand
-│   └── api-reference.md
-└── assets/
-    └── template.json
-```
-
-### SKILL.md Format
-
-````markdown
----
-name: my-skill
-description: What this skill does and when to use it. Be specific.
----
-
-# My Skill
-
-## Setup
-
-Run once before first use:
-```bash
-cd /path/to/skill && npm install
-```
-
-## Usage
-
-```bash
-./scripts/process.sh <input>
-```
-````
-
-Use relative paths from the skill directory:
-
-```markdown
-See [the reference guide](references/REFERENCE.md) for details.
-```
-
-## Frontmatter
-
-Per the [Agent Skills specification](https://agentskills.io/specification#frontmatter-required):
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens. Unlike the standard, Diffex does not require this to match the parent directory because that standard requirement is suboptimal for shared skill directories. |
-| `description` | Yes | Max 1024 chars. What the skill does and when to use it. |
-| `license` | No | License name or reference to bundled file. |
-| `compatibility` | No | Max 500 chars. Environment requirements. |
-| `metadata` | No | Arbitrary key-value mapping. |
-| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
-| `disable-model-invocation` | No | When `true`, skill is hidden from the system prompt. Users must reference it explicitly through `/skills`. |
-
-### Name Rules
-
-- 1-64 characters
-- Lowercase letters, numbers, hyphens only
-- No leading/trailing hyphens
-- No consecutive hyphens
-Diffex does not require the name to match the parent directory. The Agent Skills standard does, but that requirement is suboptimal for shared skill directories used by multiple tools.
-
-Valid: `pdf-processing`, `data-analysis`, `code-review`
-Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
-
-### Description Best Practices
-
-The description determines when the agent loads the skill. Be specific.
-
-Good:
-```yaml
-description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
-```
-
-Poor:
-```yaml
-description: Helps with PDFs.
-```
-
-## Validation
-
-Diffex validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:
-
-- Name exceeds 64 characters or contains invalid characters
-- Name starts/ends with hyphen or has consecutive hyphens
-- Description exceeds 1024 characters
-
-Unknown frontmatter fields are ignored.
-
-**Exception:** Skills with missing description are not loaded.
-
-Installed skill name precedence is project, user, then package order. Collisions warn and retain the higher-precedence installed skill. When an evolved skill has the same name, the installed skill retains the unsuffixed name and the evolved skill is exposed as `<name>-Evolved`; if that alias also collides, the evolved skill is omitted with a diagnostic.
-
-## Example
-
-```
-brave-search/
-├── SKILL.md
-├── search.js
-└── content.js
-```
-
-**SKILL.md:**
-````markdown
----
-name: brave-search
-description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
----
-
-# Brave Search
-
-## Setup
-
-```bash
-cd /path/to/brave-search && npm install
-```
-
-## Search
-
-```bash
-./search.js "query"              # Basic search
-./search.js "query" --content    # Include page content
-```
-
-## Extract Page Content
-
-```bash
-./content.js https://example.com
-```
-````
-
-## Skill Repositories
-
-- [Anthropic Skills](https://github.com/anthropics/skills) - Document processing (docx, pdf, pptx, xlsx), web development