From 7db151d28f006a31fcf8bab5d8a6d3bc4658d818 Mon Sep 17 00:00:00 2001 From: Amp Date: Sat, 18 Jul 2026 14:11:43 +0000 Subject: [PATCH 1/2] feat: add Amp docs search skill Co-authored-by: Hieu Ho --- .agents/skills/searching-amp-docs/SKILL.md | 93 ++++++++++++ .../searching-amp-docs/evals/evals.json | 41 +++++ .../references/docs-index.md | 142 ++++++++++++++++++ 3 files changed, 276 insertions(+) create mode 100644 .agents/skills/searching-amp-docs/SKILL.md create mode 100644 .agents/skills/searching-amp-docs/evals/evals.json create mode 100644 .agents/skills/searching-amp-docs/references/docs-index.md diff --git a/.agents/skills/searching-amp-docs/SKILL.md b/.agents/skills/searching-amp-docs/SKILL.md new file mode 100644 index 0000000..f077d37 --- /dev/null +++ b/.agents/skills/searching-amp-docs/SKILL.md @@ -0,0 +1,93 @@ +--- +name: searching-amp-docs +description: Searches current official Amp documentation and gives source-backed explanations of Amp features, setup, CLI usage, modes, threads, projects, orbs, runners, tools, skills, MCP, plugins, SDKs, configuration, security, pricing, and troubleshooting. Use whenever a user asks how Amp works, what Amp supports, how Amp features compare, whether behavior is current or documented, or how to accomplish something with Amp—even if they do not explicitly ask to search the docs. +--- + +# Searching Amp Docs + +Answer questions about Amp from current, official documentation. Optimize explanations for users who may not know Amp terminology yet. + +## Documentation Sources + +Use these sources for different purposes: + +- [Amp's official `llms.txt`](https://ampcode.com/llms.txt) is the machine-readable documentation entrypoint. It currently links only to the manual and SDK. +- [The Amp manual](https://ampcode.com/manual) is the primary source for product behavior and workflows. +- Specialized official pages listed in [references/docs-index.md](references/docs-index.md) are authoritative for their exact contracts, such as SDK and Plugin API details. +- Other official `ampcode.com` pages may cover current models, pricing, security, service status, account settings, or release announcements. + +The bundled index expands `llms.txt` for topic discovery, but it is not an authoritative or frozen copy of the documentation. Amp changes quickly. Read the relevant live page before answering factual questions; do not answer from either index or model memory alone. + +## Workflow + +1. Identify the user's actual goal and likely topic. Translate informal terms when necessary—for example, “cloud machine” likely means an orb and “rules file” likely means `AGENTS.md`. +2. Read `references/docs-index.md` only as much as needed to choose the best official page and section. +3. Fetch the selected page with `read_web_page`: + - Give it a specific objective containing the user's question and relevant terminology. + - Use `fullContent: true` when auditing a contract, comparing options, extracting every field, or checking whether a feature is documented. + - Use `forceRefetch: true` for “latest/current” questions and volatile information such as models, modes, pricing, limits, settings, or supported platforms. +4. If the index is missing the topic or a link is stale, check the live [`llms.txt`](https://ampcode.com/llms.txt), then use `web_search` with `site:ampcode.com` queries and read the most relevant official result. Do not substitute blogs or third-party tutorials when official documentation exists. +5. Read enough surrounding context to determine scope, prerequisites, defaults, and whether guidance is current. Search results and isolated excerpts can omit qualifiers. +6. If official pages conflict, prefer the more specific current reference over summaries, report the conflict, and avoid silently combining incompatible guidance. Use release history or source code only when the official docs are incomplete, and label that evidence separately. +7. Answer the goal directly. Include: + - a plain-language explanation; + - exact commands, settings, file locations, or code when useful; + - prerequisites, scope, defaults, and important caveats; + - links to the specific official pages used. +8. If the official docs do not answer the question, say so clearly. Separate documented behavior from any reasonable inference and suggest the narrowest next step, such as `amp --help`, `amp tools list`, `amp config keymap`, the service-status page, or Amp support. + +## New-User Guidance + +- Define Amp-specific terms on first use: thread, mode, project, orb, runner, skill, plugin, MCP server, Oracle, Librarian, and Painter. +- Prefer a short recommended path before listing alternatives. +- Explain where to run commands and whether a file is user-wide, workspace-specific, or committed to a repository. +- When several features overlap, compare them explicitly. Common distinctions include: + - local CLI vs orb vs runner; + - `AGENTS.md` vs skill vs plugin vs MCP; + - main agent vs subagent vs Oracle vs Librarian; + - thread visibility vs project membership; + - CLI execute mode vs SDK; + - `.agents/setup` vs `.agents/resume` vs `.amp/services.yaml`. +- Preserve the user's operating system and interface context. Do not give macOS-only clipboard or path instructions to a Windows/WSL user. +- Never invent a command, flag, setting, API field, keybinding, model assignment, price, or limit. Verify exact syntax in the live docs. + +## Answer Patterns + +### “How do I …?” + +Give the shortest working sequence first, then explain what each step does and mention only relevant alternatives. + +### “What is …?” + +Give a one-sentence definition, when to use it, one concrete example, and the official reference. + +### Comparison or Architecture Question + +Use a compact table when it improves clarity. Compare purpose, where it runs, persistence/scope, cost or security implications when documented, and the recommended use case. + +### Troubleshooting + +1. Confirm the platform, interface, and exact failure. +2. Check documented prerequisites and diagnostics. +3. Provide safe diagnostic commands before suggesting configuration changes. +4. For outages, check [Amp service status](https://ampcodestatus.com). +5. For unresolved client issues, explain how to generate a diagnostic report and contact support without exposing secrets. + +### “Show me every Amp feature” + +Do not paste the whole manual. Use the feature map in `references/docs-index.md` to provide a structured learning path, then offer to walk through one area with live documentation. A useful progression is: + +1. installation, interfaces, modes, and prompting; +2. threads, file mentions, images, and `AGENTS.md`; +3. projects, orbs, runners, and remote control; +4. built-in tools, skills, subagents, Oracle, Librarian, and Painter; +5. review checks, MCP, plugins, and permissions; +6. CLI automation, configuration, and SDKs; +7. pricing, enterprise controls, security, and troubleshooting. + +## Citation Rules + +- Link claims to the most specific official page available. +- For the large main manual, use the section anchor from the index when possible. +- Cite specialized references for exact SDK or plugin API contracts. +- Do not imply that this skill's bundled index is maintained by Amp or replaces the official manual. diff --git a/.agents/skills/searching-amp-docs/evals/evals.json b/.agents/skills/searching-amp-docs/evals/evals.json new file mode 100644 index 0000000..f207e42 --- /dev/null +++ b/.agents/skills/searching-amp-docs/evals/evals.json @@ -0,0 +1,41 @@ +{ + "skill_name": "searching-amp-docs", + "evals": [ + { + "id": 1, + "prompt": "I'm new to Amp and have a Vite app running in an orb. How do I let my teammate preview it, and will opening the link wake the orb and cost money?", + "expected_output": "A beginner-friendly, source-backed explanation of orb portals, service declaration or portal creation, access levels, wake behavior, and billing implications using current official Orbs documentation.", + "files": [], + "expectations": [ + "Uses the current official Orbs manual as the primary source", + "Explains the recommended portal setup with exact documented commands or file names", + "Explains access control, wake-on-request behavior, and billing without inventing values", + "Distinguishes the orb-local service address from the authenticated public portal URL" + ] + }, + { + "id": 2, + "prompt": "I keep mixing up AGENTS.md, skills, plugins, and MCP servers. Which one should I use for TypeScript conventions, a repeatable deployment workflow, blocking dangerous git commands, and connecting Linear?", + "expected_output": "A concise comparison grounded in the current Amp manual, followed by one justified recommendation for each scenario and relevant scope or security caveats.", + "files": [], + "expectations": [ + "Cites official Amp documentation for AGENTS.md, skills, plugins, and MCP", + "Correctly maps conventions to AGENTS.md and repeatable task guidance to a skill", + "Explains why event-driven policy belongs in a plugin", + "Explains when an MCP integration should be bundled with a skill rather than configured globally" + ] + }, + { + "id": 3, + "prompt": "Find the current TypeScript Amp SDK API for continuing a specific thread, choosing high mode, and making the new thread private. Give me a minimal example and don't guess any option names.", + "expected_output": "A minimal TypeScript example using option names verified against the current SDK guide/reference, with links and any relevant authentication or version prerequisites.", + "files": [], + "expectations": [ + "Reads the current official SDK guide or TypeScript reference", + "Uses the documented thread continuation, mode, and visibility option names and values", + "Includes only prerequisites and caveats supported by official documentation", + "Links to the specific official SDK source used" + ] + } + ] +} diff --git a/.agents/skills/searching-amp-docs/references/docs-index.md b/.agents/skills/searching-amp-docs/references/docs-index.md new file mode 100644 index 0000000..a7cd555 --- /dev/null +++ b/.agents/skills/searching-amp-docs/references/docs-index.md @@ -0,0 +1,142 @@ +# Amp Official Documentation Index + +This is an expanded routing index for Amp's documentation. It complements the sparse public `llms.txt`; the linked live pages remain authoritative. + +## Start Here + +- [Owner's Manual](https://ampcode.com/manual) — primary guide to installing, using, extending, configuring, and paying for Amp +- [Installation](https://ampcode.com/install) — account-specific installation and editor integration instructions +- [Modes and models](https://ampcode.com/modes) — current mode-to-model assignments +- [Pricing](https://ampcode.com/pricing) — current plan and usage pricing +- [Service status](https://ampcodestatus.com) — incidents and uptime +- [Support](https://ampcode.com/support) — official help channels + +## Owner's Manual Feature Map + +### Fundamentals + +- [Why Amp](https://ampcode.com/manual#why-amp) — product philosophy: multi-model, opinionated, frontier, and thread-based +- [Get started](https://ampcode.com/manual#get-started) — sign-in, CLI installation, updates, and initial setup +- [IDE integrations](https://ampcode.com/manual#ide) — VS Code-family editors, JetBrains, Neovim, Zed, and `ide connect` +- [Agent modes](https://ampcode.com/manual#agent-modes) — low, medium, high, and ultra +- [How to prompt](https://ampcode.com/manual#how-to-prompt) — task scoping, explicit context, planning-only requests, and verification guidance + +### Context and Interaction + +- [`AGENTS.md`](https://ampcode.com/manual#AGENTS.md) — project, subtree, personal, and organization guidance; fallback filenames +- [Granular guidance](https://ampcode.com/manual#AGENTS.md) — file mentions, globbed references, and scoped frontmatter rules +- [Referencing threads](https://ampcode.com/manual#referencing-threads) — reuse another thread by URL, ID, or `@@` search +- [Finding threads](https://ampcode.com/manual#finding-threads) — keyword and filter-based thread search +- [Archiving threads](https://ampcode.com/manual#archiving) — remove threads from the active list while retaining access +- [Attaching images](https://ampcode.com/manual#images) — clipboard and file-path image inputs +- [Mentioning files](https://ampcode.com/manual#mentioning-files) — add workspace files with `@` +- [Message editing and queueing](https://ampcode.com/manual#usage) — edit, queue, steer, or interrupt messages + +### Projects and Remote Execution + +- [Projects](https://ampcode.com/manual#projects) — repository, settings, secrets, and related threads +- [Repository](https://ampcode.com/manual#repository) — GitHub, Git URL, or Amp-hosted repositories +- [Changes workflow](https://ampcode.com/manual#changes-workflow) — ship directly or push a branch/PR +- [Orbs overview](https://ampcode.com/manual#orbs) — remote machines for unsupervised agent work +- [Full Orbs manual](https://ampcode.com/manual/orbs) — sizes, billing, terminal, sync, setup, secrets, services, and portals +- [Runners](https://ampcode.com/manual#runners) — let ampcode.com start threads on a live machine running Amp +- [Thread sharing](https://ampcode.com/manual#thread-sharing) — unlisted, workspace, group, and private visibility +- [Remote control](https://ampcode.com/manual#remote-control) — continue a running CLI thread from the web + +### Tools and Agent Capabilities + +- [Tools](https://ampcode.com/manual#tools) — built-in tools, trust model, and `amp tools list` +- [Agent skills](https://ampcode.com/manual#agent-skills) — task-specific instructions/resources and installation locations +- [Subagents](https://ampcode.com/manual#subagents) — isolated delegated work for complex or parallel tasks +- [Oracle](https://ampcode.com/manual#oracle) — frontier-model second opinion for hard reasoning, debugging, and review +- [Librarian](https://ampcode.com/manual#librarian) — deep search and explanation of public or connected private GitHub repositories +- [Painter](https://ampcode.com/manual#painter) — image generation and editing +- [Code review](https://ampcode.com/manual#code-review) — `amp review`, review requests, and custom checks + +### Extending Amp + +- [MCP](https://ampcode.com/manual#mcp) — local and remote Model Context Protocol servers +- [MCP OAuth](https://ampcode.com/manual#mcp-oauth) — automatic and manual OAuth for remote servers +- [Workspace MCP trust](https://ampcode.com/manual#mcp) — approval of workspace-defined servers +- [MCP best practices](https://ampcode.com/manual#mcp) — skill bundling, focused tool sets, and loading precedence +- [Permissions](https://ampcode.com/manual#permissions) — default tool behavior and plugin-based policy controls +- [Plugins](https://ampcode.com/manual#plugins) — TypeScript extensions for events, tools, commands, UI, and AI classification +- [Plugin locations](https://ampcode.com/manual#plugin-locations) — project, system, and workspace-global scopes +- [Writing plugins](https://ampcode.com/manual#writing-plugins) — lifecycle, reload, and plugin structure +- [Plugin events](https://ampcode.com/manual#event-examples) — `session.start`, `agent.start/end`, `tool.call/result` +- [Plugin commands, tools, UI, and agents](https://ampcode.com/manual#command-tool-and-ui-examples) — registration and custom agent examples +- [Plugin API reference](https://ampcode.com/manual/plugin-api) — end-to-end example and generated `@ampcode/plugin` types + +### CLI and Automation + +- [CLI](https://ampcode.com/manual#cli) — interactive mode, piped input, execute mode, and flags +- [Keybindings](https://ampcode.com/manual#cli-keymap) — command palette, shortcuts, and `amp.keymap` +- [Non-interactive environments](https://ampcode.com/manual#cli-non-interactive-environments) — API-key authentication for scripts and CI +- [CLI–IDE integration](https://ampcode.com/manual#cli-editor-integration) — editor context and undo-aware edits +- [Writing prompts in the CLI](https://ampcode.com/manual#cli-writing-prompts) — newlines, `$EDITOR`, and terminal behavior +- [Streaming JSON](https://ampcode.com/manual#cli-streaming-json) — structured output and streaming input flags +- [Stream JSON schema and examples](https://ampcode.com/manual/appendix#stream-json-output) — message types, subagents, images, and Claude Code compatibility + +### Configuration, Accounts, and Operations + +- [Configuration](https://ampcode.com/manual#configuration) — user/workspace settings locations and precedence +- [Settings reference](https://ampcode.com/manual#core-settings) — supported `amp.*` settings, types, and defaults +- [Enterprise managed settings](https://ampcode.com/manual#enterprise-managed-policy-settings) — organization-enforced machine policies +- [Proxies and certificates](https://ampcode.com/manual#configuration) — `HTTP_PROXY`, `HTTPS_PROXY`, and custom CA certificates +- [Pricing](https://ampcode.com/manual#pricing) — usage billing, credits, and subscription guidance +- [Enterprise](https://ampcode.com/manual#enterprise) — SSO, ZDR, controls, APIs, groups, retention, and regional providers +- [Support and platforms](https://ampcode.com/manual#support) — help channels and supported operating systems/editors + +## Orbs Manual Map + +- [What are orbs](https://ampcode.com/manual/orbs) — fresh per-thread remote machines and project configuration +- [Orb pricing and sizes](https://ampcode.com/manual/orbs) — CPU, memory, disk, billing, pause behavior +- [Starting orb threads](https://ampcode.com/manual/orbs) — web, `amp -ox`, TUI, and plugin APIs +- [Review, terminal, and `amp sync`](https://ampcode.com/manual/orbs) — inspect remote work and mirror it locally +- [Secrets and environment variables](https://ampcode.com/manual/orbs) — project runtime configuration +- [OIDC workload identity](https://ampcode.com/manual/orbs) — short-lived identity tokens for external services +- [Orb environment](https://ampcode.com/manual/orbs) — OS and preinstalled development tools +- [Setup files](https://ampcode.com/manual/orbs) — `.agents/setup`, `.agents/resume`, `.amp/services.yaml`, and portal manifests +- [Portals](https://ampcode.com/manual/orbs) — authenticated access to development servers in an orb + +## SDK Documentation + +- [SDK overview and guide](https://ampcode.com/manual/sdk) — streaming, conversations, thread continuity, configuration, MCP, and skills +- [TypeScript reference](https://ampcode.com/manual/sdk/typescript) — complete TypeScript functions, types, inputs, and messages +- [Python reference](https://ampcode.com/manual/sdk/python) — complete Python functions, types, inputs, and messages +- [Access tokens](https://ampcode.com/settings/security#access-token) — SDK and non-interactive authentication + +SDK guide topics include installation, `execute()`, message streaming, result extraction, working directory, logging, modes, reasoning effort, labels, visibility, permissions, cancellation, MCP, multi-turn input, settings files, and custom skills. + +## Appendix and Specialized References + +- [Appendix](https://ampcode.com/manual/appendix) — diagnostics, tmux, service status, enterprise controls, and Stream JSON +- [Generate a diagnostic report](https://ampcode.com/manual/appendix#report) — CLI/web reports and support workflow +- [Amp CLI in tmux](https://ampcode.com/manual/appendix#amp-cli-tmux) — extended keys and multiline input +- [MCP registry allowlist](https://ampcode.com/manual/appendix#mcp-registry-allowlist) — enterprise registry enforcement +- [Workspace thread visibility controls](https://ampcode.com/manual/appendix#workspace-thread-visibility-controls) — sharing restrictions and private defaults +- [Workspace entitlements](https://ampcode.com/manual/appendix#workspace-entitlements) — enterprise quotas and assignment precedence +- [Legacy permissions rules](https://ampcode.com/manual/appendix/legacy-permissions-rules.txt) — old settings compatibility; prefer current plugin policies for new work +- [Security reference](https://ampcode.com/security) — architecture, providers, retention, prompt injection defenses, audit logging, and disclosures +- [Workspace OpenAPI schema](https://ampcode.com/api/v2/openapi.json) — enterprise analytics and data-management API contract + +## Topic Synonyms for Search + +Use these mappings when a user's language differs from the manual: + +| User wording | Search/documentation topic | +| --- | --- | +| cloud VM, sandbox, remote machine | orb | +| local remote worker, self-hosted worker | runner | +| conversation, session, chat | thread | +| rules, instructions, memory | `AGENTS.md`, granular guidance | +| reusable prompt, workflow package | agent skill | +| extension, hook, custom command | plugin | +| external tools, tool server | MCP | +| second opinion, deep review | Oracle | +| search GitHub or dependency source | Librarian | +| generate/edit an image | Painter | +| headless, CI, scripting | execute mode, Stream JSON, or SDK | +| preview localhost remotely | orb portal | +| startup script, install dependencies | `.agents/setup` | +| restart server after orb wakes | `.agents/resume`, services | From 625f84886b9b7bfddb69aacde9c355c6bed64c21 Mon Sep 17 00:00:00 2001 From: Amp Date: Sat, 18 Jul 2026 14:21:32 +0000 Subject: [PATCH 2/2] chore: remove Amp docs skill eval fixture Co-authored-by: Hieu Ho --- .../searching-amp-docs/evals/evals.json | 41 ------------------- 1 file changed, 41 deletions(-) delete mode 100644 .agents/skills/searching-amp-docs/evals/evals.json diff --git a/.agents/skills/searching-amp-docs/evals/evals.json b/.agents/skills/searching-amp-docs/evals/evals.json deleted file mode 100644 index f207e42..0000000 --- a/.agents/skills/searching-amp-docs/evals/evals.json +++ /dev/null @@ -1,41 +0,0 @@ -{ - "skill_name": "searching-amp-docs", - "evals": [ - { - "id": 1, - "prompt": "I'm new to Amp and have a Vite app running in an orb. How do I let my teammate preview it, and will opening the link wake the orb and cost money?", - "expected_output": "A beginner-friendly, source-backed explanation of orb portals, service declaration or portal creation, access levels, wake behavior, and billing implications using current official Orbs documentation.", - "files": [], - "expectations": [ - "Uses the current official Orbs manual as the primary source", - "Explains the recommended portal setup with exact documented commands or file names", - "Explains access control, wake-on-request behavior, and billing without inventing values", - "Distinguishes the orb-local service address from the authenticated public portal URL" - ] - }, - { - "id": 2, - "prompt": "I keep mixing up AGENTS.md, skills, plugins, and MCP servers. Which one should I use for TypeScript conventions, a repeatable deployment workflow, blocking dangerous git commands, and connecting Linear?", - "expected_output": "A concise comparison grounded in the current Amp manual, followed by one justified recommendation for each scenario and relevant scope or security caveats.", - "files": [], - "expectations": [ - "Cites official Amp documentation for AGENTS.md, skills, plugins, and MCP", - "Correctly maps conventions to AGENTS.md and repeatable task guidance to a skill", - "Explains why event-driven policy belongs in a plugin", - "Explains when an MCP integration should be bundled with a skill rather than configured globally" - ] - }, - { - "id": 3, - "prompt": "Find the current TypeScript Amp SDK API for continuing a specific thread, choosing high mode, and making the new thread private. Give me a minimal example and don't guess any option names.", - "expected_output": "A minimal TypeScript example using option names verified against the current SDK guide/reference, with links and any relevant authentication or version prerequisites.", - "files": [], - "expectations": [ - "Reads the current official SDK guide or TypeScript reference", - "Uses the documented thread continuation, mode, and visibility option names and values", - "Includes only prerequisites and caveats supported by official documentation", - "Links to the specific official SDK source used" - ] - } - ] -}