indusagi-coding-agent 0.1.0 → 0.1.2

package/docs/skills.md

@@ -1,226 +1,226 @@
-> indusagi 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.
-
-Indusagi implements the [Agent Skills standard](https://agentskills.io/specification), warning about violations but remaining lenient.
-
-## 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.
-
-Indusagi loads skills from:
-
-- Global: `~/.indusagi/agent/skills/`
-- Project: `.indusagi/skills/`
-- Packages: `skills/` directories or `indusagi.skills` entries in `package.json`
-- Settings: `skills` array with files or directories
-- CLI: `--skill <path>` (repeatable, additive even with `--no-skills`)
-
-Discovery rules:
-- Direct `.md` files in the skills directory root
-- Recursive `SKILL.md` files under subdirectories
-
-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 `.indusagi/settings.json`:
-
-```json
-{
-  "skills": ["../.claude/skills"]
-}
-```
-
-## How Skills Work
-
-1. At startup, indusagi 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. Must match parent directory. |
-| `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 system prompt. Users must use `/skill:name`. |
-
-### Name Rules
-
-- 1-64 characters
-- Lowercase letters, numbers, hyphens only
-- No leading/trailing hyphens
-- No consecutive hyphens
-- Must match parent directory name
-
-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
-
-Indusagi validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:
-
-- Name doesn't match parent directory
-- Name exceeds 64 characters or contains invalid characters
-- Name starts/ends with hyphen or has consecutive hyphens
-- Description exceeds 1024 characters
-- Unknown frontmatter fields
-
-**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
-- [Indusagi Skills](https://github.com/badlogic/indusagi-skills) - Web search, browser automation, Google APIs, transcription
+> indusagi 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.
+
+Indusagi implements the [Agent Skills standard](https://agentskills.io/specification), warning about violations but remaining lenient.
+
+## 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.
+
+Indusagi loads skills from:
+
+- Global: `~/.indusagi/agent/skills/`
+- Project: `.indusagi/skills/`
+- Packages: `skills/` directories or `indusagi.skills` entries in `package.json`
+- Settings: `skills` array with files or directories
+- CLI: `--skill <path>` (repeatable, additive even with `--no-skills`)
+
+Discovery rules:
+- Direct `.md` files in the skills directory root
+- Recursive `SKILL.md` files under subdirectories
+
+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 `.indusagi/settings.json`:
+
+```json
+{
+  "skills": ["../.claude/skills"]
+}
+```
+
+## How Skills Work
+
+1. At startup, indusagi 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. Must match parent directory. |
+| `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 system prompt. Users must use `/skill:name`. |
+
+### Name Rules
+
+- 1-64 characters
+- Lowercase letters, numbers, hyphens only
+- No leading/trailing hyphens
+- No consecutive hyphens
+- Must match parent directory name
+
+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
+
+Indusagi validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:
+
+- Name doesn't match parent directory
+- Name exceeds 64 characters or contains invalid characters
+- Name starts/ends with hyphen or has consecutive hyphens
+- Description exceeds 1024 characters
+- Unknown frontmatter fields
+
+**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
+- [Indusagi Skills](https://github.com/badlogic/indusagi-skills) - Web search, browser automation, Google APIs, transcription

package/docs/terminal-setup.md

@@ -1,65 +1,65 @@
-# Terminal Setup
-
-Indusagi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
-
-## Kitty, iTerm2
-
-Work out of the box.
-
-## Ghostty
-
-Add to your Ghostty config (`~/.config/ghostty/config`):
-
-```
-keybind = alt+backspace=text:\x1b\x7f
-keybind = shift+enter=text:\n
-```
-
-## WezTerm
-
-Create `~/.wezterm.lua`:
-
-```lua
-local wezterm = require 'wezterm'
-local config = wezterm.config_builder()
-config.enable_kitty_keyboard = true
-return config
-```
-
-## VS Code (Integrated Terminal)
-
-Add to `keybindings.json` to enable `Shift+Enter` for multi-line input:
-
-```json
-{
-  "key": "shift+enter",
-  "command": "workbench.action.terminal.sendSequence",
-  "args": { "text": "\u001b[13;2u" },
-  "when": "terminalFocus"
-}
-```
-
-## Windows Terminal
-
-Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file):
-
-```json
-{
-  "actions": [
-    {
-      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
-      "keys": "shift+enter"
-    }
-  ]
-}
-```
-
-If you already have an `actions` array, add the object to it.
-
-## IntelliJ IDEA (Integrated Terminal)
-
-The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.
-
-If you want the hardware cursor visible, set `INDUSAGI_HARDWARE_CURSOR=1` before running indusagi (disabled by default for compatibility).
-
-Consider using a dedicated terminal emulator for the best experience.
+# Terminal Setup
+
+Indusagi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
+
+## Kitty, iTerm2
+
+Work out of the box.
+
+## Ghostty
+
+Add to your Ghostty config (`~/.config/ghostty/config`):
+
+```
+keybind = alt+backspace=text:\x1b\x7f
+keybind = shift+enter=text:\n
+```
+
+## WezTerm
+
+Create `~/.wezterm.lua`:
+
+```lua
+local wezterm = require 'wezterm'
+local config = wezterm.config_builder()
+config.enable_kitty_keyboard = true
+return config
+```
+
+## VS Code (Integrated Terminal)
+
+Add to `keybindings.json` to enable `Shift+Enter` for multi-line input:
+
+```json
+{
+  "key": "shift+enter",
+  "command": "workbench.action.terminal.sendSequence",
+  "args": { "text": "\u001b[13;2u" },
+  "when": "terminalFocus"
+}
+```
+
+## Windows Terminal
+
+Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file):
+
+```json
+{
+  "actions": [
+    {
+      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
+      "keys": "shift+enter"
+    }
+  ]
+}
+```
+
+If you already have an `actions` array, add the object to it.
+
+## IntelliJ IDEA (Integrated Terminal)
+
+The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.
+
+If you want the hardware cursor visible, set `INDUSAGI_HARDWARE_CURSOR=1` before running indusagi (disabled by default for compatibility).
+
+Consider using a dedicated terminal emulator for the best experience.