Agent To Quick Skill

Agent To Quick Skill

Overview

This skill converts an existing declarative chat agent, one built in some other assistant platform's low-code agent builder, into an Amazon Quick desktop skill. It is not for building a brand-new skill from scratch (just describe what you want instead), or for converting a Quick skill back out to another platform.

A declarative agent and a Quick skill are the same kind of object: a name, a description, a block of instructions, some grounding, some tools. That makes roughly 70% of a conversion mechanical. The other 30%, knowledge sources and capabilities, cannot be ported, only remapped, and remapping needs decisions from the person you are talking to. Your job is to make the mechanical part fast and the remapping explicit.

Work like a guided transfer, not a black box. The user has the source agent open in one window and Quick in the other. For every field, tell them what to copy and exactly where to paste it, including which Quick menu to open and, where the label differs across builds, both label variants. references/copy-paste-guide.md holds the field-by-field transfer instructions for all destinations. Read it before Step 2 and work from it out loud. Never say "now configure the knowledge base" without saying which window, which menu, and what text goes in it.

Prerequisites

1. Amazon Quick desktop app (macOS or Windows). Skills do not run on Quick web, mobile, or the browser extension, so the skill you produce can only be installed on desktop.
2. At least one local folder added under Settings, My computer, Local folders. You do not ask the user where to put the new skill; you find the folder their existing skills already live in. See Workflow Step 5.
3. Optional: the source agent's config file (a JSON export) placed in a connected folder. If the user does not have one, the interview path in Step 2 covers it.
4. Optional: code execution, if you want to run the bundled helper scripts in scripts/. If code execution is unavailable, do every step by reading and writing files directly; the scripts are a convenience, not a dependency.

Product naming. The target product is Amazon Quick. Never write "Amazon Quick Suite", "Quick Suite", or "AQS". Short-form "Quick" is fine after the first full mention. Do not add third-party vendor branding to any artifact you generate; describe the user's source system in whatever words they use for it.

<Workflow - Convert an agent to a Quick skill description="The full 9-step conversion, from confirming the target surface to installing the finished skill and reporting what was dropped." tools=[file_read, file_write, file_edit, folder_create, folder_list, run_python, open_in_session_tab, get_current_time] triggers=["convert my agent", "port my chat agent", "turn my agent config into a skill", "rebuild this assistant agent as a Quick skill", "convert this agent definition file"]

Step 1: Confirm the target surface

Two independent decisions. Conflating them is the single most common way this conversion goes wrong.

• Decision A, destination: skill, agent, or AGENTS.md? Determined by who uses it, where they need it, and how it gets invoked. Nothing to do with the content.
• Decision B, shape: does the output get a ## Workflow Steps section? Determined by whether the source instructions contain an ordered procedure.

Do not let Decision B answer Decision A. "The source has no ordered steps" tells you the output will have no Workflow Steps section and nothing about whether the user wants a skill, an agent, or AGENTS.md; all three exist in step-free versions. Work Decision A first, on its own.

Decision A. Ask these one message each, in order, and stop as soon as one settles it:

1. "Is this just for you, or will your team use it too?" Team use alone does not decide it (skills can be shared on desktop). Continue to Q2 and Q4.
2. "Do you need it only in the desktop app, or also on web, mobile, a browser, or a chat platform?" Anywhere beyond desktop, an agent. Skills are desktop-only. A hard capability limit, not a preference; say it plainly.
3. "Should it apply to everything you do automatically, or only when you deliberately reach for it?" Automatically, AGENTS.md. Deliberately, a skill.
4. "What grounds it, a few stable documents, or a large body of material that keeps changing?" A large changing corpus, an agent with a space (a space's knowledge base stays in sync where a bundled reference file is frozen at conversion time).

Precedence: any single agent signal wins. If Q2 or Q4 point at an agent, or Q1 revealed that central cross-surface sharing matters more than a lightweight desktop hand-off, that is the answer even if Q3 said "automatically". Do not average the answers. If the source is both a persona and a workflow (common), recommend splitting: an agent with a space for the grounding, a skill for the workflow, and say which half goes where. references/field-mapping.md has the full decision table.

Then present the named shapes as a pick-one list and get an explicit choice.

Decision B is answered by you from the source text, not asked: an ordered procedure present means write ## Workflow Steps; none present means omit it. Record it as a deliberate finding.

Success criterion: the user picked the destination from a named list. A recommendation alone does not satisfy this.

Step 2: Get the source configuration

Three paths. Ask which applies; do not guess. The deciding question is what the user has in hand, not which platform it came from. Read references/source-agent-terminology.md before this step.

• Path A, a config file exported from a low-code UI (JSON: an instructions string plus capabilities/actions arrays). Confirm it is in a connected folder and read it. With code execution: python3 scripts/parse_manifest.py <config.json> --out intake.md. Without: read the JSON and fill assets/intake.template.md by hand.
• Path B, no file; the agent exists only in the source UI. Interview field by field, in the order in references/source-agent-terminology.md, one field per message.
• Path C, a markdown definition file (structured metadata, then a prose body). The same parser handles it. This is shorter and differently shaped: skip the interview (name, description, body port near-verbatim), the tools: translation is the real work (vocabularies are disjoint; a wrong name fails silently), audit the body for shell dependencies (Quick has no shell), and elicit knowledge sources from the user directly (a markdown definition has no knowledge field).

Insist on two things on every path:

• Instructions verbatim. On A and C they are in the file; on B, have the user select-all and paste the whole instructions box. Never a summary.
• A baseline output. Have them run the agent on its most representative task and paste the result. It is the only way to verify the conversion in Step 7. Ask now; access to the source is easy to lose.

Success criterion: a filled intake with sections 1-3 and 8 complete, plus section 6 on Paths A/B.

Step 3: Remap knowledge sources and capabilities

This is the gate. Do not proceed past it with anything unresolved. Read references/knowledge-and-tools-remap.md and work its per-source decision procedure.

Connect natively first; downloading a copy is the last resort. Work down this landing-spot list in order and take the first that fits:

1. Connection to the library, cloud storage, mail, chat, CRM, or ticketing the source lives in (Settings, Capabilities, Connections), then reference by link.
2. Knowledge base in a space, for a whole library, site, or changing corpus (Quick web).
3. MCP server, where the system has one and no first-class connector.
4. A built-in Quick skill: web browsing for public URLs, code execution, image generation.
5. Local folder, when the file lives on the user's machine or the library is synced to disk.
6. Reference file bundled in the skill folder, for small stable material (a rubric, template, list).
7. Dropped, but say so out loud in the Step 8 report.

Never make the user download a file when a connector could reach it: a copy freezes the content, breaks per-person sharing, is manual work repeated on every update, and can move data out of its permission boundary. A failed fetch or sign-in wall means "add the connection", not "download it".

Elicit every source; do not wait to be offered it. Source instructions routinely point at material that lives outside the agent ("refer to the Brand Guidelines"). For each source, one question per message, stopping when one resolves it: (1) "Can you paste the link?" (2) "Is that library already connected?" and if not, "Can you add the connection?" (3) only if no connector, "Is there a synced local copy?" (4) if none of these, record it as dropped and name the consequence. A link needs two more questions: one document vs a whole library (a library needs a space, which may send you back to Step 1), and public vs permission-controlled (browsing cannot authenticate to a permissioned link).

Say what you extracted and where it landed before moving on, so the user can catch a wrong document. Record any copy as a dated snapshot and name the staleness in Step 8. Red Data is a hard stop.

For capabilities: code execution and image generation map to built-in skills (code execution is an upgrade, a real local file system, not a substitution); an API action maps to an action connector or MCP built from the same specification; a nested sub-agent becomes a separate skill or scheduled task.

Success criterion: every row in intake sections 4 and 5 reads remapped or dropped. None reads unresolved.

Step 4: Choose the identity fields

Propose each and get agreement, one question per message, in this order.

• "What do you want to call the new skill?" Ask explicitly; offer the source name as the default and say what it would produce (display_name and the kebab-case folder name).
• name: kebab-case of the chosen name. Must exactly match the folder name in Step 5. Propose a shortening if it exceeds about 40 characters.
• display_name: the chosen name, verbatim.
• icon: one emoji (the source raster icon is not portable). Propose one rather than asking open-endedly.
• trigger: 2 to 4 words, derived from the job the agent does, not from a starter prompt (seeding from one prompt narrows matching and misses the agent's range). Check it does not collide with a built-in skill (Agents & skills, Skills, BUILT-IN SKILLS).
• description: the source description near-verbatim, with the starter-prompt vocabulary appended (that phrasing widens matching and belongs here, not in the trigger).

Success criterion: the user answered "what to call it" and approved the trigger specifically, and the trigger matches the agent's whole range rather than one task.

Step 5: Write the skill folder

Locate the skills folder; do not ask where to save it. Use folder_list to read connected local folders, find the directory whose subdirectories contain SKILL.md files, and write there. Exactly one candidate: use it and state the path in one line. More than one: the only case where you ask, as a pick-one list with skill counts. None: create skills/ in a connected folder and say you did.

Create <skill-name>/ with SKILL.md, an optional references/ (anything a source knowledge item became), and an optional scratchpad.md (Step 9). Start from assets/SKILL.template.md; read references/quick-skill-format.md first. Restructure the source instructions, do not paste: the "You are a..." opening becomes ## Overview, a numbered procedure becomes ## Workflow Steps, always/never guidelines become ## Best Practices, "if you cannot find..." becomes failure handling, long examples and rubrics become references/ files.

The frontmatter must be a real YAML block, and you must read it back. Line 1 is exactly ---; a line that is exactly --- closes it; one key per line at column 1; no # in front of any key; nothing above the opening ---. After writing, read the file back and confirm all five. See <Gotchas> for the silent-failure this prevents. Never hardcode an absolute path into the output.

Success criterion: a SKILL.md whose frontmatter you have read back and confirmed parses.

Step 6: Validate and package

With code execution: python3 scripts/package_skill.py <path>/<skill-name> --out <skill-name>.zip. It checks the frontmatter contract before zipping. Fix every error; read every warning to the user. Without code execution, check by hand: frontmatter contract (as Step 5), name is kebab-case and equals the folder name, no <placeholder>/TODO survives, no absolute user-specific paths in the body, and the zip's top-level entry is the skill folder.

Success criterion: a .zip whose single top-level entry is <skill-name>/.

Step 7: Install and verify

Walk the user through it, offering both menu labels (only one is present on their build):

1. Amazon Quick desktop, Settings.
2. Capabilities, Skills, or Agents & skills, Skills.
3. Upload, or the purple + Create, Import from file. Select the .zip.
4. Restart Quick desktop. It will not activate until they do. Processing can take five minutes; if Quick does not recognise it, restart again.
5. Set up the Step 3 prerequisites: connections and local folders.

Then verify in order, do not skip to 3: (1) "Tell me about ", Quick should describe it; if not, the upload did not land, restart. (2) Say the trigger phrase; confirm it loads. (3) Run the representative starter prompt and compare against the Step 2 baseline.

Success criterion: step 3's output is materially equivalent to the baseline, or the differences are understood and explained.

Step 8: Report

Give the user four sections; be blunt in the last two:

• Ported: which fields carried over.
• Remapped: each knowledge source and capability, and where it landed.
• Dropped: name each individually. Always includes the icon image (replaced by an emoji) and the first-invoke display of the starter prompts (Quick has no prompt-chip surface; tell them the trigger phrase instead). Add any workflow steps the source did not contain and were therefore not invented, and every source the user chose not to rebuild.
• Prerequisites still outstanding: connectors or folders not yet configured, and what the skill gets wrong until they are.

Do not soften the Dropped section or fold it into prose. A named gap is actionable; a vague one is a support ticket later.

Step 9: Offer the follow-ups

• improve the <skill name> skill, after the first real run.
• A scratchpad.md in the skill folder, for a durable improvement loop (an Improvement Queue and Lessons Learned). Checkboxes are the sole source of truth: agents have no memory between sessions, so an unchecked box stays undone regardless of what was discussed.
• A scheduled task (Settings, Capabilities, Schedules), if the source ran on a cadence. Its prompt must be written for a zero-context agent and must not ask for plan approval at runtime.
• AGENTS.md instead, if the source was really encoding standing preferences rather than a workflow. It is a governance file read at the start of every session (Settings, Customization, Response preferences), not uploaded to the skill registry.

When a step cannot complete as written, consult references/failure-handling.md for the full table of failure modes and their remedies.

</Workflow - Convert an agent to a Quick skill>

Example invocations

• "convert my agent"
• "convert my agent to a Quick skill"
• "I have an agent config JSON, turn it into a skill"
• "port my chat agent over to Quick desktop"
• "rebuild this assistant agent as a Quick skill"
• "here's my agent's instructions and knowledge sources, migrate it"
• "convert this agent definition file to a Quick skill"
• "port this SKILL.md over to Quick desktop"

Reference files

• references/copy-paste-guide.md: field-by-field, what to copy from the source and exactly where to paste it in Quick, with menu paths, for all destinations. Read before Step 2; use through Steps 5 and 7.
• references/source-agent-terminology.md: every source-platform configuration concept and what to capture from it. Read before Step 2.
• references/field-mapping.md: the field-by-field mapping table, instruction-restructuring patterns, and the skill-vs-agent decision. Read before Steps 1 and 5.
• references/knowledge-and-tools-remap.md: the per-source decision procedure, the landing-spot table, and the tools: rules. Read before Step 3.
• references/quick-skill-format.md: the Quick SKILL.md frontmatter contract and body conventions. Read before Step 5.
• references/failure-handling.md: the full failure-mode table, grouped by workflow phase. Read whenever a step cannot complete.
• assets/intake.template.md: the intake sheet to fill in Step 2.
• assets/SKILL.template.md: the output scaffold for Step 5.
• scripts/parse_manifest.py: parses a source config into a filled intake.
• scripts/package_skill.py: validates frontmatter and zips the folder.