aws-samples/scaffold-workshop

Scaffold Workshop

Generate boilerplate files for a new AgentCore workshop, then draft workshop-specific content by researching AWS documentation and following established patterns.

Usage

• /scaffold-workshop 05_evaluation — Scaffold and draft content for step 05
• /scaffold-workshop 08_policy --title "AgentCore Policy" — Scaffold with a custom title
• /scaffold-workshop 09_browser_use --title "AgentCore Browser Use" --description "Web automation with persistent browser profiles" — Full custom scaffold

Arguments

$ARGUMENTS contains the workshop directory name and optional flags.

Parse $ARGUMENTS for:

• Positional: directory name (required, e.g. 05_evaluation)
• --title: Workshop title (optional, will be inferred from directory name if not given)
• --description: One-line description (optional, will be drafted if not given)

Steps

1. Resolve parameters

Parse $ARGUMENTS to extract dir_name, --title, and --description.

If --title is missing, infer it from the directory name:

• 05_evaluation → "AgentCore Evaluation"
• 08_policy → "AgentCore Policy"
• 09_browser_use → "AgentCore Browser Use"

If --description is missing, ask the user with AskUserQuestion what the workshop should cover, or let them provide a free-text description.

2. Run the scaffold script

cd <project_root>
uv run python .claude/tools/scaffold_workshop.py <dir_name> --title "<title>" --description "<description>"

If files already exist, the script will SKIP them (safe to re-run). Inform the user which files were created vs skipped.

3. Research the feature

Search AWS documentation for the AgentCore feature covered by this workshop:

• Use WebSearch to find relevant AWS docs, blog posts, and SDK references
• Use WebFetch to read key documentation pages
• Look at existing workshop implementations in the repo for patterns (Glob + Read)

Gather:

• The main boto3 / SDK client and API calls involved
• Key concepts and terminology
• Typical setup → use → cleanup lifecycle
• Prerequisites and IAM permissions needed

4. Draft README content

Edit the generated README.md to replace TODO markers with drafted content.

CRITICAL: Preserve all heading levels (#, ##, ###) and the overall section order exactly as generated by the scaffold template. Only replace the TODO placeholder text and code block contents — never remove, rename, or reorder headings.

Replace TODO content in each section:

• Process Overview: Replace the TODO mermaid diagram with one showing actual service interactions
• Prerequisites: Replace TODO items with real AWS permissions and prior workshop dependencies
• File Structure: Update the tree with likely files the workshop will contain
• Step 1/2 headings: Replace TODO: First Action etc. with real action names, fill in commands and explanations
• Key Implementation Pattern subsections: Replace ### TODO: Setup Pattern etc. with named patterns (e.g., ### Policy Client Setup), add real code snippets based on SDK docs
• Usage Example: Replace pass with a complete working code example
• Benefits section: Replace TODO bullets with real benefits of the feature
• References: Replace placeholder links with actual AWS documentation URLs

Mark any content that needs verification with <!-- DRAFT: verify this --> HTML comments.

5. Draft README_ja.md content

Edit the generated README_ja.md to mirror the English README:

• Preserve all heading levels (#, ##, ###) and section order exactly
• Translate only the prose and TODO text to Japanese — keep heading structure intact
• Keep code blocks, mermaid diagrams, and technical terms in English
• Follow the same translation patterns as existing README_ja.md files (e.g., 01, 03, 06)

6. Draft clean_resources.py

Edit the generated clean_resources.py with realistic cleanup logic:

• Identify what AWS resources the workshop will create
• Add proper boto3 client setup and API calls for deletion
• Follow the pattern from existing cleanup scripts (06_identity, 07_gateway)
• Keep TODO markers for resource IDs that depend on runtime config

7. Summary

Print a summary of what was created and drafted:

• List all files created/modified
• Note which sections still need manual review (marked with <!-- DRAFT -->)
• Suggest next steps (implement the main test script, verify API calls, etc.)

Reference: Existing Workshop Patterns

Directory → Feature mapping

| Directory | Feature | Category | |-----------|---------|----------| | 01-05 | Foundation capabilities | Foundation | | 06-09 | Extension capabilities | Extension |

Section heading patterns (English / Japanese)

| English | Japanese | |---------|----------| | Process Overview | プロセス概要 | | Prerequisites | 前提条件 | | How to use | 使用方法 | | File Structure | ファイル構成 | | Step N: | ステップN: | | Key Implementation Pattern | 主要な実装パターン | | Usage Example | 使用例 | | References | 参考資料 | | Next Steps | 次のステップ |

clean_resources.py pattern

• Read config from JSON file (if applicable)
• Create boto3 client: boto3.client("bedrock-agentcore-control", region_name=region)
• Delete resources in reverse dependency order
• Print status for each deletion
• Remove config files at the end
• Guard with if __name__ == "__main__":

Important Notes

• Never overwrite files the user has already edited — check with AskUserQuestion first
• All drafted content should use real AWS API names and SDK patterns
• Follow CLAUDE.md: no dummy data, meaningful names, proper error handling
• The scaffold script lives at .claude/tools/scaffold_workshop.py