@protolabsai/proto 0.14.0

package/dist/bundled/qc-helper/docs/features/skills.md

@@ -0,0 +1,289 @@
+# Agent Skills
+
+> Create, manage, and share Skills to extend Qwen Code's capabilities.
+
+This guide shows you how to create, use, and manage Agent Skills in **Qwen Code**. Skills are modular capabilities that extend the model's effectiveness through organized folders containing instructions (and optionally scripts/resources).
+
+## Prerequisites
+
+- Qwen Code (recent version)
+- Basic familiarity with Qwen Code ([Quickstart](../quickstart.md))
+
+## What are Agent Skills?
+
+Agent Skills package expertise into discoverable capabilities. Each Skill consists of a `SKILL.md` file with instructions that the model can load when relevant, plus optional supporting files like scripts and templates.
+
+### How Skills are invoked
+
+Skills are **model-invoked** — the model autonomously decides when to use them based on your request and the Skill's description. This is different from slash commands, which are **user-invoked** (you explicitly type `/command`).
+
+If you want to invoke a Skill explicitly, use the `/skills` slash command:
+
+```bash
+/skills <skill-name>
+```
+
+Use autocomplete to browse available Skills and descriptions.
+
+### Benefits
+
+- Extend Qwen Code for your workflows
+- Share expertise across your team via git
+- Reduce repetitive prompting
+- Compose multiple Skills for complex tasks
+
+## Create a Skill
+
+Skills are stored as directories containing a `SKILL.md` file.
+
+### Personal Skills
+
+Personal Skills are available across all your projects. Store them in `~/.qwen/skills/`:
+
+```bash
+mkdir -p ~/.qwen/skills/my-skill-name
+```
+
+Use personal Skills for:
+
+- Your individual workflows and preferences
+- Skills you're developing
+- Personal productivity helpers
+
+### Project Skills
+
+Project Skills are shared with your team. Store them in `.qwen/skills/` within your project:
+
+```bash
+mkdir -p .qwen/skills/my-skill-name
+```
+
+Use project Skills for:
+
+- Team workflows and conventions
+- Project-specific expertise
+- Shared utilities and scripts
+
+Project Skills can be checked into git and automatically become available to teammates.
+
+## Write `SKILL.md`
+
+Create a `SKILL.md` file with YAML frontmatter and Markdown content:
+
+```yaml
+---
+name: your-skill-name
+description: Brief description of what this Skill does and when to use it
+---
+
+# Your Skill Name
+
+## Instructions
+Provide clear, step-by-step guidance for Qwen Code.
+
+## Examples
+Show concrete examples of using this Skill.
+```
+
+### Field requirements
+
+Qwen Code currently validates that:
+
+- `name` is a non-empty string
+- `description` is a non-empty string
+
+Recommended conventions (not strictly enforced yet):
+
+- Use lowercase letters, numbers, and hyphens in `name`
+- Make `description` specific: include both **what** the Skill does and **when** to use it (key words users will naturally mention)
+
+## Add supporting files
+
+Create additional files alongside `SKILL.md`:
+
+```text
+my-skill/
+├── SKILL.md (required)
+├── reference.md (optional documentation)
+├── examples.md (optional examples)
+├── scripts/
+│   └── helper.py (optional utility)
+└── templates/
+    └── template.txt (optional template)
+```
+
+Reference these files from `SKILL.md`:
+
+````markdown
+For advanced usage, see [reference.md](reference.md).
+
+Run the helper script:
+
+```bash
+python scripts/helper.py input.txt
+```
+````
+
+## View available Skills
+
+Qwen Code discovers Skills from:
+
+- Personal Skills: `~/.qwen/skills/`
+- Project Skills: `.qwen/skills/`
+- Extension Skills: Skills provided by installed extensions
+
+### Extension Skills
+
+Extensions can provide custom skills that become available when the extension is enabled. These skills are stored in the extension's `skills/` directory and follow the same format as personal and project skills.
+
+Extension skills are automatically discovered and loaded when the extension is installed and enabled.
+
+To see which extensions provide skills, check the extension's `qwen-extension.json` file for a `skills` field.
+
+To view available Skills, ask Qwen Code directly:
+
+```text
+What Skills are available?
+```
+
+Or inspect the filesystem:
+
+```bash
+# List personal Skills
+ls ~/.qwen/skills/
+
+# List project Skills (if in a project directory)
+ls .qwen/skills/
+
+# View a specific Skill's content
+cat ~/.qwen/skills/my-skill/SKILL.md
+```
+
+## Test a Skill
+
+After creating a Skill, test it by asking questions that match your description.
+
+Example: if your description mentions "PDF files":
+
+```text
+Can you help me extract text from this PDF?
+```
+
+The model autonomously decides to use your Skill if it matches the request — you don't need to explicitly invoke it.
+
+## Debug a Skill
+
+If Qwen Code doesn't use your Skill, check these common issues:
+
+### Make the description specific
+
+Too vague:
+
+```yaml
+description: Helps with documents
+```
+
+Specific:
+
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.
+```
+
+### Verify file path
+
+- Personal Skills: `~/.qwen/skills/<skill-name>/SKILL.md`
+- Project Skills: `.qwen/skills/<skill-name>/SKILL.md`
+
+```bash
+# Personal
+ls ~/.qwen/skills/my-skill/SKILL.md
+
+# Project
+ls .qwen/skills/my-skill/SKILL.md
+```
+
+### Check YAML syntax
+
+Invalid YAML prevents the Skill metadata from loading correctly.
+
+```bash
+cat SKILL.md | head -n 15
+```
+
+Ensure:
+
+- Opening `---` on line 1
+- Closing `---` before Markdown content
+- Valid YAML syntax (no tabs, correct indentation)
+
+### View errors
+
+Run Qwen Code with debug mode to see Skill loading errors:
+
+```bash
+qwen --debug
+```
+
+## Share Skills with your team
+
+You can share Skills through project repositories:
+
+1. Add the Skill under `.qwen/skills/`
+2. Commit and push
+3. Teammates pull the changes
+
+```bash
+git add .qwen/skills/
+git commit -m "Add team Skill for PDF processing"
+git push
+```
+
+## Update a Skill
+
+Edit `SKILL.md` directly:
+
+```bash
+# Personal Skill
+code ~/.qwen/skills/my-skill/SKILL.md
+
+# Project Skill
+code .qwen/skills/my-skill/SKILL.md
+```
+
+Changes take effect the next time you start Qwen Code. If Qwen Code is already running, restart it to load the updates.
+
+## Remove a Skill
+
+Delete the Skill directory:
+
+```bash
+# Personal
+rm -rf ~/.qwen/skills/my-skill
+
+# Project
+rm -rf .qwen/skills/my-skill
+git commit -m "Remove unused Skill"
+```
+
+## Best practices
+
+### Keep Skills focused
+
+One Skill should address one capability:
+
+- Focused: "PDF form filling", "Excel analysis", "Git commit messages"
+- Too broad: "Document processing" (split into smaller Skills)
+
+### Write clear descriptions
+
+Help the model discover when to use Skills by including specific triggers:
+
+```yaml
+description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or .xlsx data.
+```
+
+### Test with your team
+
+- Does the Skill activate when expected?
+- Are the instructions clear?
+- Are there missing examples or edge cases?

package/dist/bundled/qc-helper/docs/features/sub-agents.md

@@ -0,0 +1,307 @@
+# Sub-Agents
+
+Delegate focused tasks to specialized AI agents with their own system prompts, tool restrictions, and model selection.
+
+This page covers how to create and use sub-agents, the configuration format, built-in agents, and multi-agent team coordination.
+
+## Create a sub-agent
+
+Sub-agents are Markdown files with YAML frontmatter stored in `.proto/agents/` (project) or `~/.proto/agents/` (global). Project agents take precedence over global agents with the same name.
+
+### Minimal example
+
+Create `.proto/agents/code-reviewer.md`:
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for quality, security, and maintainability
+tools:
+  - read_file
+  - grep_search
+  - glob
+---
+
+You are a code reviewer. Analyze code for:
+
+- Security vulnerabilities
+- Performance issues
+- Maintainability concerns
+
+Provide specific, actionable feedback with file paths and line numbers.
+```
+
+### Use the agent
+
+Ask the model naturally and it will delegate based on the `description` field:
+
+```
+Review the authentication module for security issues
+```
+
+Or invoke explicitly:
+
+```
+Use the code-reviewer agent to check my recent changes
+```
+
+### Management commands
+
+| Command          | Purpose                            |
+| ---------------- | ---------------------------------- |
+| `/agents create` | Guided agent creation wizard       |
+| `/agents manage` | View, edit, delete existing agents |
+
+## Configuration reference
+
+### Frontmatter fields
+
+| Field                        | Required | Description                                        |
+| ---------------------------- | -------- | -------------------------------------------------- |
+| `name`                       | Yes      | Unique identifier (lowercase, hyphens, 2-50 chars) |
+| `description`                | Yes      | When to delegate to this agent                     |
+| `tools`                      | No       | Allowlist of permitted tools. Omit to inherit all. |
+| `disallowedTools`            | No       | Denylist of tools to exclude from inherited set    |
+| `permissionMode`             | No       | `default`, `plan`, `autoEdit`, `yolo`              |
+| `modelConfig.model`          | No       | `haiku`, `sonnet`, `opus`, or full model ID        |
+| `modelConfig.temp`           | No       | Temperature (0-2)                                  |
+| `runConfig.max_turns`        | No       | Maximum agentic turns                              |
+| `runConfig.max_time_minutes` | No       | Maximum execution time                             |
+| `color`                      | No       | Display color for UI                               |
+
+### Tool restrictions
+
+Two mechanisms control which tools an agent can use:
+
+**Allowlist (`tools`)** — Only these tools are available:
+
+```yaml
+tools:
+  - read_file
+  - grep_search
+  - glob
+```
+
+**Denylist (`disallowedTools`)** — Remove these from the inherited set:
+
+```yaml
+disallowedTools:
+  - write_file
+  - edit
+```
+
+When both are specified, `disallowedTools` is applied first, then `tools` filters the remainder.
+
+### Permission mode
+
+Override the session's permission mode for a specific agent:
+
+| Mode       | Behavior                         |
+| ---------- | -------------------------------- |
+| `default`  | Standard confirmation prompts    |
+| `plan`     | Read-only, no file modifications |
+| `autoEdit` | Auto-approve file edits          |
+| `yolo`     | Auto-approve everything          |
+
+If the parent session uses bypass permissions, it takes precedence.
+
+### Template variables
+
+System prompts support `${variable}` syntax. Variables are resolved from `ContextState` at runtime.
+
+### Storage hierarchy
+
+| Level     | Location                        | Priority |
+| --------- | ------------------------------- | -------- |
+| Session   | Passed via SDK at runtime       | Highest  |
+| Project   | `.proto/agents/`                | 2        |
+| User      | `~/.proto/agents/`              | 3        |
+| Extension | Installed extension's `agents/` | 4        |
+| Built-in  | Embedded in proto               | Lowest   |
+
+When multiple agents share the same name, higher-priority location wins.
+
+## Built-in agents
+
+Four agents are always available:
+
+| Agent             | Purpose                                              | Tools              |
+| ----------------- | ---------------------------------------------------- | ------------------ |
+| `general-purpose` | Complex multi-step tasks, code search                | All (except Agent) |
+| `Explore`         | Fast codebase search and analysis                    | Read-only          |
+| `verify`          | Review changes for correctness before finalizing     | Read-only          |
+| `coordinator`     | Orchestrate multi-agent work with task decomposition | All + Agent        |
+
+## Background execution
+
+Agents can run in the background using `run_in_background: true` in the Agent tool call:
+
+- Returns immediately with an agent ID
+- Runs concurrently while the main conversation continues
+- Completion notification is injected at the next tool boundary
+- Results appear alongside tool results via mid-turn injection
+
+The `coordinator` agent uses this to delegate subtasks in parallel.
+
+## Agent teams
+
+Teams enable coordinated multi-agent work with shared task visibility and messaging.
+
+### Team commands
+
+| Command                                | Description               |
+| -------------------------------------- | ------------------------- |
+| `/team list`                           | List all configured teams |
+| `/team start <name> [member:type ...]` | Create and start a team   |
+| `/team status <name>`                  | Show team member status   |
+| `/team stop <name>`                    | Stop a running team       |
+| `/team delete <name>`                  | Delete a team config      |
+
+### Start a team
+
+```
+/team start research researcher:Explore implementer:general-purpose
+```
+
+Default (no members specified): `lead` (coordinator) + `scout` (Explore).
+
+Team config is stored at `.proto/teams/{name}/config.json`.
+
+### Shared task list
+
+Teammates share task visibility through the task system:
+
+- **Claim a task**: `claimTask(id, agentId)` atomically assigns and starts it
+- **Find available work**: `getUnclaimedTasks()` returns pending tasks with no assignee
+- Tasks track their `assignee` for ownership
+
+### Inter-agent messaging
+
+`TeamMailbox` enables direct communication:
+
+| Method                     | Purpose                             |
+| -------------------------- | ----------------------------------- |
+| `send(from, to, message)`  | Direct message to a teammate        |
+| `broadcast(from, message)` | Message all teammates except sender |
+| `receive(agentId)`         | Drain unread messages               |
+| `peek(agentId)`            | Read without draining               |
+
+### Team lifecycle hooks
+
+Three hook events fire during team coordination:
+
+| Hook            | When it fires                                              |
+| --------------- | ---------------------------------------------------------- |
+| `TeammateIdle`  | Background agent finishes (exit 2 = reject, send feedback) |
+| `TaskCreated`   | Task added to shared list                                  |
+| `TaskCompleted` | Task marked done                                           |
+
+See [Hooks](./hooks.md#team-events) for configuration details.
+
+## Design guidelines
+
+### Single responsibility
+
+Each agent should have one clear purpose.
+
+```yaml
+# Focused
+name: testing-expert
+description: Writes comprehensive unit and integration tests
+
+# Too broad
+name: general-helper
+description: Helps with testing, documentation, review, and deployment
+```
+
+### Actionable descriptions
+
+Write descriptions that clearly indicate when to delegate:
+
+```yaml
+# Clear trigger
+description: Reviews code for security vulnerabilities, performance issues, and maintainability
+
+# Vague
+description: A helpful code reviewer
+```
+
+### Minimal tool access
+
+Grant only the tools the agent needs. Read-only agents should not have `write_file` or `edit`.
+
+### Proactive delegation
+
+Include "use proactively" in the description to encourage automatic delegation without explicit user request.
+
+## SDK subagent configuration
+
+When using the [TypeScript SDK](../reference/sdk-api.md), pass subagent configurations directly via the `agents` option. The primary agent decides when to invoke each subagent based on its `description`.
+
+```typescript
+import { query, type SubagentConfig } from '@qwen-code/sdk';
+
+const reviewer: SubagentConfig = {
+  name: 'code-reviewer',
+  description:
+    'Reviews code for bugs, security issues, and performance problems',
+  systemPrompt: `You are a code reviewer. Review diffs for:
+- Logic errors and edge cases
+- Security vulnerabilities
+- Performance regressions
+Output a structured review with severity levels.`,
+  level: 'session',
+  tools: ['Read', 'Glob', 'Grep', 'Bash'],
+  modelConfig: { model: 'claude-sonnet-4-6' },
+};
+
+const conversation = query({
+  prompt: 'Review the changes in the current branch',
+  options: { agents: [reviewer] },
+});
+```
+
+### SubagentConfig fields
+
+| Field                        | Required | Type        | Description                                        |
+| ---------------------------- | -------- | ----------- | -------------------------------------------------- |
+| `name`                       | Yes      | `string`    | Unique identifier                                  |
+| `description`                | Yes      | `string`    | When to delegate to this agent                     |
+| `systemPrompt`               | Yes      | `string`    | System prompt for the subagent                     |
+| `level`                      | Yes      | `'session'` | Subagent scope (currently only `'session'`)        |
+| `tools`                      | No       | `string[]`  | Allowlist of permitted tools. Omit to inherit all. |
+| `modelConfig.model`          | No       | `string`    | Model ID or alias (`haiku`, `sonnet`, `opus`)      |
+| `modelConfig.temp`           | No       | `number`    | Temperature (0-2)                                  |
+| `runConfig.max_turns`        | No       | `number`    | Maximum agentic turns                              |
+| `runConfig.max_time_minutes` | No       | `number`    | Maximum execution time in minutes                  |
+| `color`                      | No       | `string`    | Display color                                      |
+
+### Multiple subagents with different models
+
+```typescript
+const architect: SubagentConfig = {
+  name: 'architect',
+  description: 'Designs system architecture and makes high-level decisions',
+  systemPrompt: 'You are a senior architect...',
+  level: 'session',
+  modelConfig: { model: 'claude-opus-4-6' },
+};
+
+const implementer: SubagentConfig = {
+  name: 'implementer',
+  description: 'Implements code changes based on specifications',
+  systemPrompt: 'You implement code changes...',
+  level: 'session',
+  tools: ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash'],
+  modelConfig: { model: 'claude-sonnet-4-6' },
+};
+
+const conversation = query({
+  prompt: 'Design and implement the caching layer',
+  options: { agents: [architect, implementer] },
+});
+```
+
+SDK-configured subagents have the highest priority in the [storage hierarchy](#storage-hierarchy) (session level). They override project or user agents with the same name.
+
+See the [SDK subagent examples](../../developers/examples/sdk-agents.md) for more patterns.

package/dist/bundled/qc-helper/docs/features/token-caching.md

@@ -0,0 +1,29 @@
+# Token Caching and Cost Optimization
+
+Qwen Code automatically optimizes API costs through token caching when using API key authentication. This feature stores frequently used content like system instructions and conversation history to reduce the number of tokens processed in subsequent requests.
+
+## How It Benefits You
+
+- **Cost reduction**: Less tokens mean lower API costs
+- **Faster responses**: Cached content is retrieved more quickly
+- **Automatic optimization**: No configuration needed - it works behind the scenes
+
+## Token caching is available for
+
+- API key users (Qwen API key, OpenAI-compatible providers)
+
+## Monitoring Your Savings
+
+Use the `/stats` command to see your cached token savings:
+
+- When active, the stats display shows how many tokens were served from cache
+- You'll see both the absolute number and percentage of cached tokens
+- Example: "10,500 (90.4%) of input tokens were served from the cache, reducing costs."
+
+This information is only displayed when cached tokens are being used, which occurs with API key authentication but not with OAuth authentication.
+
+## Example Stats Display
+
+![Qwen Code Stats Display](https://img.alicdn.com/imgextra/i3/O1CN01F1yzRs1juyZu63jdS_!!6000000004609-2-tps-1038-738.png)
+
+The above image shows an example of the `/stats` command output, highlighting the cached token savings information.

package/dist/bundled/qc-helper/docs/ide-integration/_meta.ts

@@ -0,0 +1,4 @@
+export default {
+  'ide-integration': 'Introduction',
+  'ide-companion-spec': 'IDE Companion Spec',
+};