skill-builder

Overview

Produces a tested, reusable agent skill for the user's own use case, from a description, an agent prompt, or an existing workflow.

Workflow

<Definition - Quick Skills Standard> The Amazon Quick agent skills standard uses a prescriptive standard for creating a skill directory, structured prompting with XML tags, and Amazon Quick's requirements. </Definition - Quick Skills Standard>

<Definition - Skill Directory Structure> A skill is a directory containing:

• SKILL.md: The only required file. Contains YAML frontmatter (metadata for discovery) and a markdown body (instructions for execution).
• scripts/: Executable code the agent runs during a workflow step. Self-contained, callable, returns a result. Example: scripts/analyze_logs.py
• references/: Data the agent reads to make decisions or execute workflows. Example: references/ticket-routing.md
• assets/: Static resources that shape or appear in the deliverable. Templates the agent fills in, schemas to validate against, images to include. The user receives these. Example: assets/my-data.json
• evals/: Test cases that verify the skill works correctly. Contains evals.json, eval output, and optionally evals/files/ for test input data.
• README.md: Optional human-facing overview, pre-requisites, installation, and getting-started. Mandatory when the skill has any dependency (Rule 25). Its presence is signaled by the readme frontmatter field. </Definition - Skill Directory Structure>

<Definition - Frontmatter> The YAML block between --- delimiters at the top of SKILL.md. All possible fields:

• name (required): Kebab-case identifier. Lowercase + hyphens only, max 64 chars. Must match directory name.
• display_name (optional): Human-friendly name shown in UI.
• icon (optional): Emoji identifier.
• description (required): Max 1024 chars. What the skill does and when to use it. Imperative phrasing, include trigger keywords. When a user asks what version of the skill they are on, refer them to the last_updated field.
• created_date (required): ISO date the skill was first created. Format: YYYY-MM-DD.
• last_updated (required): ISO date the skill was last modified. Format: YYYY-MM-DD.
• tools (optional): Built-in Amazon Quick tools this skill calls directly (e.g., file_read, web_search). Anything that needs an external integration (a connector, local MCP, or coding agent) is documented in the README ## Pre-requisites, not here.
• readme (optional): Instruction for the agent about the skill's README.md, present only when a README exists. It is the machine-readable signal that the agent must read the README before running, which is mandatory when the skill has any dependency (Rule 25). The README ## Pre-requisites declares each dependency (type, which connector, cloud or local runtime, required or optional) and ## Installation points to the reference docs in <Resources>. Example: readme: "Read README.md before running. Its ## Pre-requisites lists required connectors; verify each is available and stop if a required one is missing."
• preferred_model (optional): Recommended model tier: fast, balanced, or smart. If omitted, the skill runs on the user's session tier.
• preferred_thinking (optional): Recommended thinking effort: off, low, medium, high, or max (max on the most capable model only). Advisory, like preferred_model.
• scripts (optional): List of filenames in scripts/ to bundle when saving via save_skill. Example: scripts: [analyze_logs.py, format_output.py]
• checksum (required): Integrity digest of the skill's core files (SKILL.md, README.md, scripts/, references/, assets/; evals/, tests/, and transient files excluded), in the form sha256:<hex>. Generated by scripts/create_checksum.py (its single owner), which excludes this line from its own hash so writing it back is idempotent. Regenerated on save; check_skill.py requires it and verifies it is present and well-formed on audit.
• inputs (optional): Parameters that vary between invocations. Each input has:
  • name (required): identifier used as {{name}} placeholder
  • description (required): what this input is for
  • type (optional): string, url, path, number, choice, boolean
  • options (required if type is choice): list of valid values
  • required (optional): true/false
  • default (optional): value if not provided </Definition - Frontmatter>

<Definition - Progressive Disclosure> Skill description loaded at startup for all skills. Full SKILL.md loaded on activation. Other files loaded on demand during execution. </Definition - Progressive Disclosure>

<Definition - Evals> Test cases used to verify a skill behavior. Stored in evals/evals.json.

The file is a JSON object with:

• skill_name (required): name of the skill being tested.
• evals (required): list of test cases. Each case is an object with:
  • id (required): numeric identifier.
  • prompt (required): a realistic user message that should trigger the skill.
  • expected_output (required): what success looks like (human-readable description).
  • assertions (optional): list of verifiable checks. Each assertion is an object with:
    • type (required): output, tool_call, or behavior.
    • check (required): what to verify. Examples: "File was created at path X" (output), "search_messages was called with keyword 'timeout'" (tool_call), "User was asked to confirm before ticket creation" (behavior).
  • files (optional): list of input file paths relative to evals/files/. </Definition - Evals>

<Definition - XML Blocks> Each block type and what belongs in it. Some carry a "Test:" placement check, a question an author asks to decide whether a piece of content belongs in that block. It is an authoring aid, not something the running agent executes.

• <Identity>: Who the agent IS. Posture, expertise, disposition, NOT a restatement of the task. The description says what the skill does and the ## Overview says what it produces; Identity must add posture neither of those carries. Test: "If asked 'who are you?', could you answer with this?"
• <Goal>: Success criteria. Measurable outcomes you could evaluate a run against.
• <Rules>: Your behavioral constraints on the agent. Test: "Would the agent's default behavior violate YOUR standards without this?"
• <Definitions>: Terms the agent would otherwise misinterpret.
• <Agent Annotations>: How to interpret step prefixes and notation.
• <Tools>: Available tools declared inline in the body. Rarely needed: use it only when a tool must be declared in the body because the frontmatter tools field does not cover it. Most skills declare tools in frontmatter and omit this block.
• <Gotchas>: Non-obvious environment facts that contradict likely assumptions. Test: "Would the agent make a FACTUAL ERROR without this?"
• <Instructions>: Wrapper containing all <Workflow> blocks.
• <Workflow - X>: Step-by-step procedures using [Agent]/[Ask user]/[Decide] prefixes. Required inline attributes: description="...", tools=[built_in_tool, ...], triggers=["when X", "when Y"]. Optional advisory execution hints (guidance to the orchestrating agent, not service-enforced): background=true if the workflow's work should run as a spawned task, preferred_model=fast|balanced|smart, preferred_thinking=off|low|medium|high|max. Test: "Does this tell the agent what to DO in sequence?"
• <Templates>: Output format templates referenced by workflows on-demand. Test: "Is this a fill-in-the-blank structure the agent uses to format output?"
• <Resources>: Lookup data the agent references during execution. Tables, URLs, channel maps. Test: "Is this data to LOOK UP, not internalize?" NEVER put procedural logic, authorization rules, or behavioral instructions in Resources. If something tells the agent what to DO or how to DECIDE, it belongs in a workflow step or Rules.

Block ordering (top to bottom): Identity, Goal, Definitions, Rules, Agent Annotations, Gotchas, Instructions (Workflows), Templates (if needed), Resources (if needed). The agent reads sequentially: context and constraints before procedures, lookup data last. </Definition - XML Blocks>

<Definition - Description Writing Formula> Format: [What it does, one sentence] + [Trigger phrases: "Use when asked to..." with 5-8 quoted variations] + [Edge cases: "or any..." catch-all]. This skill's own description is a working example. </Definition - Description Writing Formula>

<Workflow - Router description="Determine what the user needs and dispatch to the correct phase." tools=[] triggers=["User asks to build, create, modify, save, test, or audit a skill", "sb help or any sb command"]

1. [Decide] What is the user asking? Validate: Exactly one path is chosen. If ambiguous, ask user to clarify before proceeding.
   • Create a new skill → <Workflow - Plan>
   • Modify an existing skill → <Workflow - Plan> (load existing skill as context first)
   • Convert a just-completed workflow into a skill → <Workflow - Plan> (use extract_session_data in step 3 to pull tools and context from the live session)
   • Continue building a skill already planned → <Workflow - Build>
   • Save a skill that's ready → <Workflow - Save>
   • Test a skill → <Workflow - Eval>
   • Check a skill against the standard → <Workflow - Audit>
   • sb help, a bare sb, or "what can skill-builder do" → <Workflow - Help>
   • A specific sb command dispatches straight to its workflow: sb plan → <Workflow - Plan>, sb build → <Workflow - Build>, sb save → <Workflow - Save>, sb eval → <Workflow - Eval>, sb audit → <Workflow - Audit> </Workflow - Router>

<Workflow - Help description="Render the skill-builder command menu, or dispatch a specific sb command." tools=[] triggers=["sb help", "sb", "User asks what skill-builder can do or how to use it"]

1. [Agent] Render <Template - Help Menu> populated for skill-builder, then stop and wait for the user's choice. The Router sends only menu requests here (sb help, a bare sb, or "what can skill-builder do"); a specific sb command is dispatched by the Router straight to its workflow. Validate: the menu lists every command with a one-line description. If fails: re-render from <Template - Help Menu>. </Workflow - Help>

<Workflow - Plan description="Research, identify requirements, and determine the approach." tools=[file_read, file_rag_search, web_search, extract_session_data] triggers=["Create a new skill", "Modify an existing skill", "Convert a workflow into a skill"]