# Scaffold Workshop

> Scaffold and draft a new AgentCore workshop. Use when someone wants to create, scaffold, or start a new workshop directory with boilerplate and initial content.

- Skill: `aws-samples/scaffold-workshop` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aws-samples/scaffold-workshop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/scaffold-workshop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aws-samples (https://skillmd.com/u/aws-samples)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/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

```bash
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`