docs: complete prompts documentation with custom agents/commands and summary

Author: claude

PROMPTS_DOCUMENTATION.md

@@ -962,3 +962,203 @@ $ARGUMENTS
 
 ---
 
+## Custom Agent/Command Prompts
+
+These are user-defined agents and commands stored in the `.opencode/` directory. They extend OpenCode's functionality with project-specific behaviors.
+
+### Agent Structure
+
+Custom agents are Markdown files with YAML frontmatter located in:
+- `.opencode/agent/*.md`
+- `agent/**/*.md` (nested agents supported)
+
+**Format:**
+```markdown
+---
+description: When to use this agent
+mode: subagent | primary
+---
+
+Agent prompt content goes here...
+```
+
+### Command Structure
+
+Custom commands are Markdown files with YAML frontmatter located in:
+- `.opencode/command/*.md`
+- `command/**/*.md`
+
+**Format:**
+```markdown
+---
+description: What this command does
+---
+
+Command template with $1, $2, $ARGUMENTS placeholders
+```
+
+### Example Custom Agents
+
+#### 1. Git Committer Agent
+
+**File:** `.opencode/agent/git-committer.md`
+
+**Purpose:** Handles git commit and push operations with specific commit message guidelines.
+
+**Configuration:**
+```markdown
+---
+description: Use this agent when you are asked to commit and push code changes to a git repository.
+mode: subagent
+---
+
+You commit and push to git
+
+Commit messages should be brief since they are used to generate release notes.
+
+Messages should say WHY the change was made and not WHAT was changed.
+```
+
+**Key Guidelines:**
+- Brief commit messages for release notes
+- Focus on "why" not "what"
+- Subagent mode (can be called by primary agent)
+
+#### 2. Documentation Agent
+
+**File:** `.opencode/agent/docs.md`
+
+**Purpose:** Specialized agent for writing technical documentation with specific formatting rules.
+
+**Configuration:**
+```markdown
+---
+description: ALWAYS use this when writing docs
+---
+
+You are an expert technical documentation writer
+
+You are not verbose
+
+The title of the page should be a word or a 2-3 word phrase
+
+The description should be one short line, should not start with "The", should
+avoid repeating the title of the page, should be 5-10 words long
+
+Chunks of text should not be more than 2 sentences long
+
+Each section is separated by a divider of 3 dashes
+
+The section titles are short with only the first letter of the word capitalized
+
+The section titles are in the imperative mood
+
+The section titles should not repeat the term used in the page title, for
+example, if the page title is "Models", avoid using a section title like "Add
+new models". This might be unavoidable in some cases, but try to avoid it.
+
+Check out the /packages/web/src/content/docs/docs/index.mdx as an example.
+
+For JS or TS code snippets remove trailing semicolons and any trailing commas
+that might not be needed.
+
+If you are making a commit prefix the commit message with `docs:`
+```
+
+**Key Guidelines:**
+- Not verbose
+- Short titles (1-3 words)
+- Brief descriptions (5-10 words, no "The")
+- Max 2 sentences per paragraph
+- Section dividers: `---`
+- Imperative mood for section titles
+- Capitalize only first letter
+- No trailing semicolons/commas in JS/TS snippets
+- Commit prefix: `docs:`
+
+### Example Custom Commands
+
+#### 1. Commit Command
+
+**File:** `.opencode/command/commit.md`
+
+**Purpose:** Shortcut command for committing and pushing changes.
+
+**Configuration:**
+```markdown
+---
+description: Git commit and push
+---
+
+commit and push
+make sure it includes a prefix like docs:, tui:, core:...
+```
+
+**Usage:** User can type `/commit` to trigger this command template.
+
+#### 2. Spellcheck Command
+
+**File:** `.opencode/command/spellcheck.md`
+
+**Purpose:** Runs spellcheck on specified files or directories.
+
+**Configuration:**
+```markdown
+---
+description: Run spellcheck on files
+---
+
+run spellcheck on $ARGUMENTS
+```
+
+**Usage:** User can type `/spellcheck <files>` and `$ARGUMENTS` will be replaced with the specified files.
+
+#### 3. Hello Command
+
+**File:** `.opencode/command/hello.md`
+
+**Purpose:** Simple test command for verification.
+
+**Configuration:**
+```markdown
+---
+description: Say hello
+---
+
+say hello
+```
+
+**Usage:** User can type `/hello` to test custom commands.
+
+### Built-in Agents
+
+OpenCode includes three built-in agents defined in `/packages/opencode/src/agent/agent.ts`:
+
+1. **general** - Research, searching code, multi-step tasks (subagent mode)
+2. **build** - Primary agent for solving tasks (primary mode)
+3. **plan** - Planning and analysis phase (primary mode, read-only permissions)
+
+### Loading Mechanism
+
+Agents and commands are loaded from:
+- Local project: `.opencode/agent/*.md`, `.opencode/command/*.md`
+- Nested: `agent/**/*.md`, `command/**/*.md`
+- Built-in agents: Defined in code
+
+The YAML frontmatter becomes configuration, and the Markdown content becomes the `prompt` field (for agents) or `template` field (for commands).
+
+---
+
+## Summary
+
+OpenCode uses a sophisticated multi-layered prompting system:
+
+1. **System Prompts:** Provider-specific core instructions (14 variants)
+2. **Mode Control:** Plan (read-only) and Build (read-write) enforcement
+3. **Utility Prompts:** Title generation and conversation summarization
+4. **Agent Generation:** Dynamic creation of new custom agents
+5. **Command Templates:** Repository initialization and setup
+6. **Custom Agents/Commands:** User-defined project-specific extensions
+
+All prompts work together to create a flexible, powerful AI coding assistant that adapts to different models, modes, and user requirements while maintaining consistent behavior and high code quality.
+