@greppleai/grip 0.0.0-stage → 0.1.3

package/docs/settings.md

@@ -0,0 +1,372 @@
+# Settings
+
+Grip uses JSON settings files with project settings overriding global settings.
+
+| Location | Scope |
+|----------|-------|
+| `~/.grip/agent/settings.json` | Global (all projects) |
+| `.grip/settings.json` | Project (current directory) |
+
+Edit directly or use `/settings` for common options.
+
+## Hook settings
+
+Hooks use a Claude Code-compatible schema and are captured as an immutable per-session snapshot. Native Grip settings are preferred: trusted user hooks are read from the active `<agentDir>/settings.json` (normally `~/.grip/agent/settings.json`) before the compatibility source `~/.claude/settings.json`. For local interactive startup, project hooks trigger a **Don't trust / Trust once / Trust always** prompt. Trust once covers only the initial session; Trust always records the canonical repository location in `<agentDir>/trusted-project-hooks.json` and includes all future changes at that location. `--trust-project-hooks` bypasses the prompt. Trusted project sources are read from `.grip/settings.json`, `.claude/settings.json`, and `.claude/settings.local.json` in that order; exact duplicates from later sources are ignored. Approved project command hooks follow the active workspace backend, executing inside a sandbox after the session switches to it; project HTTP hooks are blocked there rather than escaping through host networking. Initial remote project discovery remains disabled. Hook parse/schema/execution problems appear as nonfatal `GripAgent` diagnostics. SDK hosts can disable discovery, inject a trusted snapshot, and restrict HTTP URLs/environment interpolation with `CreateGripAgentOptions.hooks`.
+
+## All Settings
+
+### Model & Thinking
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `defaultProvider` | string | - | Default provider (e.g., `"anthropic"`, `"openai"`) |
+| `defaultModel` | string | - | Default model ID |
+| `compressionDetectionModel` | string | - | Global-only `provider/model-id` for background compression recommendations. Selection with `/compress-detection-model` enables detection for the current session only. Saved selections stay inactive unless enabled with `/compress-detection on` or `GRIP_CONTEXT_COMPRESSION_DETECTION=1`. Unset makes no detection requests. |
+| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` |
+| `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
+| `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) |
+| `quietStartup` | boolean | `false` | Hide startup header |
+| `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
+| `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks |
+| `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) |
+| `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
+| `showHardwareCursor` | boolean | `false` | Show terminal cursor |
+| `tuiMode` | string | `"regular"` | Interactive TUI mode: `"regular"` uses the main screen and terminal scrollback; experimental `"fullscreen"` uses an application-owned viewport. `/settings` changes apply immediately and persist; `--tui-mode` overrides the startup value |
+| `fullscreenExitOutput` | string | `"transcript"` | Fullscreen exit output: `"transcript"` replays the complete logical transcript, while `"resume-hint"` restores the previous main screen without replaying transcript content so any shell or launcher resume affordance remains visible. Has no effect in regular TUI mode |
+| `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows a draggable thumb temporarily while scrolling or hovering it, `"always"` reserves the rightmost column and keeps the draggable thumb visible, and `"hidden"` disables it. Has no effect in regular TUI mode |
+
+### Telemetry and update checks
+
+`enableInstallTelemetry` only controls the anonymous install/update ping to the **upstream** `https://pi.dev/api/report-install` endpoint still used by this checkout; it is not a verified Grip service. Opting out of telemetry does not disable update checks; Grip can still fetch npm metadata for `@greppleai/grip` to look for the latest version when that package exists in the registry.
+
+Set `GRIP_SKIP_VERSION_CHECK=1` to disable the Grip version update check. Use `--offline` or `GRIP_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry. Set `GRIP_TELEMETRY=0` or `enableInstallTelemetry: false` to disable the upstream telemetry ping alone.
+
+### 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
+  }
+}
+```
+
+### 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 bounded retry for transient agent-turn, compaction, and branch-summary errors |
+| `retry.maxRetries` | number | `3` | Maximum additional attempts for agent turns and summary operations |
+| `retry.baseDelayMs` | number | `2000` | Base delay for 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. Provider-level attempts happen inside each agent-turn or summary attempt, so enabling both layers multiplies the possible request count. SDK/provider retries may also handle out-of-usage-limit errors before Grip sees them, which can block until provider quota resets.
+
+```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 | `"sse"` | Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, or `"auto"` |
+
+### 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 |
+| `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) |
+| `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 `~/.grip/agent/npm/`; project-scoped npm packages install under `.grip/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.
+
+### Tool Configuration
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `enableSubagents` | boolean | `false` | Enable the built-in `subagent`, `subagent_runs`, and `create_subagent` tools by default. Changes made in `/settings` apply immediately; `/reload` applies file edits. Explicit CLI/SDK tool allowlists can opt in to any subset, while no-tools modes remain authoritative. |
+| `enableLspTools` | boolean | `false` | Expose configured `lsp_*` tools by default. `--enable-lsp-tools` opts in for one CLI invocation; `/reload` applies settings-file edits. The LSP runtime still requires separate configuration; explicit tool allowlists override this default. |
+| `tools` | object | `{}` | Per-tool configuration keyed by tool name |
+| `tools.websearch.provider` | string | `"duckduckgo"` | Web search provider: `"duckduckgo"`, `"brave"`, or `"firecrawl"` |
+| `tools.websearch.apiKey` | string | - | Provider API key. Brave env fallback: `GRIP_WEBSEARCH_BRAVE_API_KEY` or `BRAVE_SEARCH_API_KEY`. Firecrawl env fallback: `GRIP_WEBSEARCH_FIRECRAWL_API_KEY` or `FIRECRAWL_API_KEY` |
+| `tools.websearch.baseUrl` | string | Provider default API URL | Override the Brave or Firecrawl endpoint for compatible/proxy APIs |
+
+```json
+{
+  "tools": {
+    "websearch": {
+      "provider": "firecrawl",
+      "apiKey": "YOUR_FIRECRAWL_API_KEY"
+    }
+  }
+}
+```
+
+Global and project `tools` settings merge per tool name, so a project can override `tools.websearch.baseUrl` while keeping a global `tools.websearch.apiKey`. Environment variables remain supported for `websearch`; explicit settings take precedence. Firecrawl uses `POST /v2/search` with web results only.
+
+### Lima Sandbox
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `sandbox.limaBinary` | string | `"limactl"` | Lima executable |
+| `sandbox.limaTemplate` | string | `"template:docker-rootful"` | Template used to create a managed VM |
+| `sandbox.limaInstanceNamePrefix` | string | `"grip-sandbox"` | Generated VM name prefix |
+| `sandbox.workspaceMountPath` | string | `"/workspace"` | Guest path for the mounted current workspace |
+| `sandbox.daemonPort` | number | `8787` | Preferred loopback-forwarded daemon port; an available port is selected when occupied for new VMs |
+| `sandbox.daemonHostBind` | string | `"127.0.0.1"` | Host bind for the daemon forward |
+| `sandbox.cleanup` | string | `"stop"` | Stop behavior: `"stop"` or `"remove"` for owned VMs |
+
+```json
+{
+  "sandbox": {
+    "limaBinary": "limactl",
+    "cleanup": "remove"
+  }
+}
+```
+
+Precedence for sandbox starts is `--template`, `GRIP_SANDBOX_*` environment variables, project settings, global settings, then defaults. See [Lima Sandbox](sandbox.md) for command syntax, environment variables, and security notes.
+
+
+For a running shared Lima VM, `/sandbox start --name` uses `sandbox.workspaceMountPath`, `sandbox.daemonHostBind`, `sandbox.daemonPort` and `sandbox.limaBinary` to verify its fixed writable parent mount and loopback forward before attaching. `sandbox.cleanup` does not authorize stopping or deleting the shared VM. Auth, config and sessions remain on the host; same-user agents share the default host directory unless each selects a distinct `GRIP_CODING_AGENT_DIR`. Shared writes and edits use revision preconditions, but shell writes can still race. Shared transfers are unavailable; guest process execution requires trusted clients. See [sandbox.md](sandbox.md#direct-shared-lima-attachment).
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `sessionDir` | string | - | Directory where session files are stored. Accepts absolute or relative paths, plus `~`. |
+
+```json
+{ "sessionDir": ".grip/sessions" }
+```
+
+When multiple sources specify a session directory, precedence is `--session-dir`, `GRIP_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) |
+| `modelProfiles` | object | `{}` | Named snapshots created with `/profile create <name>` |
+
+```json
+{
+  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"],
+  "modelProfiles": {
+    "deep": ["anthropic/claude-opus-4-7:high", "openai-codex/gpt-5.6"],
+    "fast": ["anthropic/claude-haiku-4-5", "google/gemini-3-flash-preview"]
+  }
+}
+```
+
+`/profile create <name>` snapshots the current scoped model list. `/profile use <name>` restores that list for the current session and saves it as the global `enabledModels` default. A project-level `enabledModels` override still takes precedence on future startup. Profiles are stored in the global settings file. Creating an existing name replaces its snapshot.
+
+### Markdown
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `markdown.codeBlockIndent` | string | `"  "` | Indentation for code blocks |
+| `markdown.mermaid` | string | `"streaming"` | Terminal Mermaid rendering: `"off"`, `"final"`, or `"streaming"`. Invalid values fall back to `"streaming"` |
+
+Built-in Mermaid rendering applies only to ordinary user and assistant messages in the interactive transcript. `"final"` keeps streaming assistant fences as source until the message finishes; `"streaming"` renders best-effort partial diagrams while streaming. The built-in does not render Mermaid in thinking or custom messages, summaries, print/RPC/JSON output, or HTML export, and never changes session storage or model context.
+
+### Language Servers
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `lsp` | object | - | Validated external language-server configuration layer |
+
+Grip does not include a default language server. Configure spawned or attached servers explicitly:
+
+```json
+{
+  "lsp": {
+    "servers": [
+      {
+        "id": "rust",
+        "selectors": [{ "languageId": "rust", "pattern": "**/*.rs" }],
+        "transport": { "type": "tcp", "host": "127.0.0.1", "port": 9257 },
+        "lifecycle": { "type": "attached" },
+        "workspace": { "type": "session" }
+      }
+    ]
+  }
+}
+```
+
+Global and project `lsp` values are separate layers; project definitions override complete servers by ID. Active project-settings transports and positive top-level `enabled: true` activation are blocked unless an SDK host grants `trustProjectLspTransports`; this host-only decision cannot be enabled by project settings. Safe disable/removal entries remain effective. Malformed or unreadable LSP sources produce visible nonfatal diagnostics at the applicable error or warning severity and disable LSP; `--no-lsp` remains available as a per-invocation recovery path. CLI and host layers have higher precedence. See [Language Server Protocol](lsp.md) for spawn examples, merge/replace/disable semantics, trust, roots, transports, remote path mapping, and troubleshooting.
+
+### Resources
+
+These settings define where to load extensions, skills, rules, prompts, and themes from.
+
+Paths in `~/.grip/agent/settings.json` resolve relative to `~/.grip/agent`. Paths in `.grip/settings.json` resolve relative to `.grip`. 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 |
+| `rules` | string[] | `[]` | Local rule file paths or directories |
+| `prompts` | string[] | `[]` | Local prompt template paths or directories |
+| `themes` | string[] | `[]` | Local theme file paths or directories |
+| `enableSkillCommands` | boolean | `true` | Register skills and rules as `/skill:name` and `/rule:name` commands |
+
+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": ["pi-skills", "@org/my-extension"]
+}
+```
+
+Object form filters which resources to load:
+
+```json
+{
+  "packages": [
+    {
+      "source": "pi-skills",
+      "skills": ["brave-search", "transcribe"],
+      "extensions": []
+    }
+  ]
+}
+```
+
+See [packages.md](packages.md) for package management details. `pi-skills` above is an illustrative third-party package identifier, not a project-owned package name or Grip alias.
+
+## 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": ["pi-skills"]
+}
+```
+
+## Project Overrides
+
+Project settings (`.grip/settings.json`) override global settings. Nested objects are merged, except `lsp`, which uses the server-ID layer semantics documented in [Language Servers](#language-servers):
+
+```json
+// ~/.grip/agent/settings.json (global)
+{
+  "theme": "dark",
+  "compaction": { "enabled": true, "reserveTokens": 16384 }
+}
+
+// .grip/settings.json (project)
+{
+  "compaction": { "reserveTokens": 8192 }
+}
+
+// Result
+{
+  "theme": "dark",
+  "compaction": { "enabled": true, "reserveTokens": 8192 }
+}
+```

package/docs/shell-aliases.md

@@ -0,0 +1,13 @@
+# Shell Aliases
+
+Grip runs bash in non-interactive mode (`bash -c`), which doesn't expand aliases by default.
+
+To enable your shell aliases, add to `~/.grip/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

@@ -0,0 +1,246 @@
+> Grip 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.
+
+Grip implements the [Agent Skills standard](https://agentskills.io/specification), warning about most violations but remaining lenient. Grip 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.
+
+Grip loads skills from:
+
+- Global:
+  - `~/.grip/agent/skills/`
+  - `~/.agents/skills/`
+- Project:
+  - `.grip/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 `grip.skills` entries in `package.json`
+- Settings: `skills` array with files or directories
+- CLI: `--skill <path>` (repeatable, additive even with `--no-skills`)
+
+Discovery rules:
+- In `~/.grip/agent/skills/` and `.grip/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 `.grip/settings.json`:
+
+```json
+{
+  "skills": ["../.claude/skills"]
+}
+```
+
+## How Skills Work
+
+1. At startup, Grip scans skill locations and extracts names and descriptions
+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 prompting or `/skill:name` to force it)
+4. The agent follows the instructions, using relative paths to reference scripts and assets
+
+This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
+
+## Skill Commands
+
+Skills register as `/skill:name` commands:
+
+```bash
+/skill:brave-search           # Load and execute the skill
+/skill:pdf-tools extract      # Load skill with arguments
+```
+
+Arguments after the command are appended to the skill content as `User: <args>`.
+
+Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
+
+```json
+{
+  "enableSkillCommands": true
+}
+```
+
+## 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, Grip 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). |
+| `tools` | No | Tool name or YAML list of lazy tools to load automatically when the skill is loaded via `read` or `/skill:name`. |
+| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. Users must use `/skill:name`. |
+
+Example with associated lazy tools:
+
+```yaml
+---
+name: github-pr-workflow
+description: Create and update GitHub PRs following repository policy.
+tools:
+  - github_create_pr
+  - github_get_pr
+---
+```
+
+When the agent loads this skill, Grip loads those tools into the active tool context for the next turn.
+
+### Name Rules
+
+- 1-64 characters
+- Lowercase letters, numbers, hyphens only
+- No leading/trailing hyphens
+- No consecutive hyphens
+Grip 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
+
+Grip 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.
+
+Name collisions (same name from different locations) warn and keep the first skill found.
+
+## 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
+- [Pi Skills](https://github.com/badlogic/pi-skills) - Web search, browser automation, Google APIs, transcription