template-builder

Derived from .claude/agents/template-builder.md. Treat platform-specific tool names or delegation instructions as Codex equivalents.

Authoritative Sources

• GitHub Issue Templates — https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository
• GitHub Pull Request Templates — https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository
• GitHub Discussion Templates — https://docs.github.com/en/discussions/managing-discussions-for-your-community/creating-discussion-category-forms

Template Builder Agent

Shared instructions

Skills: github-workflow-standards, github-scanning

A magical interactive agent that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. Instead of writing YAML, answer simple questions and the agent generates the template for you.

Template Builder Agent

Shared instructions

Skills: github-workflow-standards, github-scanning

A magical interactive agent that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. Instead of writing YAML, answer simple questions and the agent generates the template for you.

How to Use

In VS Code

1. Open Copilot Chat (Ctrl+Shift+I Windows, Cmd+Shift+I macOS)
2. Type: @template-builder or /build-template
3. The agent will ask you a series of questions to understand your template
4. Answer each question in the Ask Questions prompts
5. The agent generates your complete YAML template
6. Copy the output to .github/ISSUE_TEMPLATE/your-template-name.yml

In GitHub Web

1. Open Copilot Chat (Copilot button in top right)
2. Mention: @template-builder
3. Type your template goals (e.g., "I want to build an accessibility bug report template")
4. The agent provides step-by-step YAML scaffolding you can copy and refine

Example Workflow

You: @template-builder create accessibility bug template

Agent asks (via Ask Questions):

1. Template name? -> You answer: "Accessibility Bug Report"
2. What's this template for? -> "Report screen reader and keyboard issues"
3. First field? -> "Screen Reader (dropdown)"
4. Dropdown options? -> "NVDA, JAWS, VoiceOver, Other"
5. Is it required? -> "Yes"
6. Next field? -> "Browser (dropdown)" ... (continues for each field)

Agent outputs: Complete YAML template ready to paste

---

Template Builder Guide: Step-by-Step

Phase 1: Gather Template Metadata

The agent starts by asking core questions about your template:

Questions:

• What is the template name? (e.g., "Bug Report", "Feature Request", "Accessibility Issue")
• One-line description of this template's purpose
• Default title prefix for issues (e.g., "[BUG]", "[A11Y]", "[FEAT]")
• What labels should this template auto-apply? (comma-separated)

Agent generates:

name: Your Template Name
description: Your description
title: "[TAG] "
labels: ["label1", "label2"]

---

Phase 2: Build Form Fields Interactively

The agent walks through adding fields one-by-one:

Questions for each field:

1. Field type? -> Show options:

   • markdown (instructional text)
   • input (single-line text)
   • textarea (multi-line text)
   • dropdown (select from options)
   • checkboxes (multiple selections)

2. Field label? (required)

3. Help text / description? (optional)

4. Is this field required? (yes/no)

5. For textarea: Should code highlighting be enabled? (markdown, python, javascript, etc.)

6. For dropdown: What are the options? (comma-separated or one per line)

7. For dropdown: Can user select multiple? (yes/no)

8. Another field? (yes/no)

Agent generates field YAML:

  - type: dropdown
    id: screen-reader
    attributes:
      label: Screen Reader
      description: Which screen reader are you using?
      options:
        - NVDA
        - JAWS
        - VoiceOver
    validations:
      required: true

---

Phase 3: Generate Complete Template

Once all fields are entered, the agent:

1. Asks for final review:

   • "Does this capture all the information you need?"
   • "Any fields to reorder or remove?"

2. Generates the complete YAML:

   • Full frontmatter with all metadata
   • All fields in order
   • Proper validation setup
   • Formatted and ready to copy

3. Provides usage instructions:

   • Where to save the file (.github/ISSUE_TEMPLATE/your-name.yml)
   • How to test it
   • How to edit it later
   • How to add it to the template chooser via config.yml

---

Pre-Built Workflow: Guided Accessibility Template

The agent includes a guided workflow for the most common case: building an accessibility bug report template.

Invoke with:

• @template-builder + "create accessibility template"
• /build-a11y-template

Workflow:

The agent skips to Phase 2 but pre-populates it with accessibility-specific fields:

1. Component affected? (dropdown with agent names)
2. Screen reader (with NVDA, JAWS, VoiceOver, TalkBack, etc. pre-options)
3. Browser version
4. Operating system
5. Expected behavior vs actual behavior
6. Steps to reproduce
7. WCAG success criterion (dropdown with criteria)
8. Before submitting checklist (checkboxes for verification)

Output: Production-ready accessibility bug template you can immediately use.

---

Advanced: Customize the Template Builder

The Template Builder agent itself can be extended. Students in the workshop can:

1. Add new field types -> Extend the agent to support custom validations
2. Create workflow templates -> Pre-built templates for specific issue types (Security, Documentation, etc.)
3. Add conditional fields -> Show/hide fields based on previous answers
4. Export to markdown -> Generate Markdown templates in addition to YAML
5. Template sharing -> Generate a code block to share with other projects

---

Integration with Nexus

The Template Builder works alongside the five core agents:

Together: The five agents automate workflow; the Template Builder automates the infrastructure that makes workflows possible.

---

Day 2 Amplifier: From Manual to Magical

---

Hands-On Exercise: Build Your Own Template Builder

During the workshop (Chapter 16), you will extend this agent:

Exercise 1: Generate Your Project's Template

1. Open VS Code
2. Activate Copilot Chat
3. Type: @template-builder + describe your project's needs
4. Follow the Ask Questions flow
5. Save the generated YAML to your fork

Exercise 2: Add a Workflow Variant

The base agent handles general templates. Add a security-template or documentation-template variant:

1. Open the Template Builder agent definition
2. Add a new slash command: /build-security-template
3. Pre-populate field questions for security-specific data (vulnerability type, severity, affected versions)
4. Test it with @template-builder + "create security template"

Exercise 3: Export to Markdown

Currently the agent outputs YAML. Add a follow-up step:

1. After generating YAML, ask: "Also generate a Markdown version?"
2. Convert the YAML field structure to Markdown template format
3. Output both versions so users can choose

Exercise 4: Create a Template Showcase

Collect anonymous templates built by workshop participants:

1. Your template works - share it
2. Create a PR to .github/community-templates/
3. List your template (name, description, field count) in COMMUNITY_TEMPLATES.md
4. Other participants can reference or fork your template

---

Technical Details: VS Code Ask Questions Integration

The Template Builder uses VS Code's Ask Questions feature to create an interactive wizard. Here's how it works internally:

Phase 1: Initial Questions

Agent asks (via Ask Questions UI):
- Template name?
  [Input field with placeholder "e.g., Bug Report"]
  
- What is this template for?
  [Text area with prompt text]
  
Accept / Cancel buttons below

Phase 2: Field-by-Field Loop

Agent displays:
"Add a field to your template"

[Dropdown: Select field type]
[Input: Field label]
[Textarea: Description]
[Checkbox: Required?]
[Checkbox: For textarea - enable code highlighting?]
[Dynamic input: For dropdown - add options]

[Add Another Field] [Finish]

Phase 3: Review

Agent shows:
"Here's your YAML template. Ready?"

[Syntax-highlighted code block]

[Copy to Clipboard] [Edit] [Save to file]

When the user clicks "Copy to Clipboard", the agent provides instructions:

1. Go to VS Code Explorer
2. Navigate to .github/ISSUE_TEMPLATE/
3. New file: your-template-name.yml
4. Paste the YAML
5. Save and commit

---

Troubleshooting & Tips

Issue: "I want to reorder my fields"

After the template is generated, ask: @template-builder reorder fields + paste your YAML. The agent will show you a visual reordering interface or provide the reordered YAML.

Issue: "I want to edit just one field"

Reply to the agent: "Change field 3 to a textarea instead of input" and the agent regenerates with that one change.

Tip: "Save time by describing your entire template at once"

Instead of using Ask Questions, you can paste a template description:

@template-builder

Create a template with:
- Component dropdown (values: Agent A, Agent B, Agent C)
- Severity dropdown (required)
- Detailed description textarea
- Steps to reproduce textarea
- Before submitting: 2 checkboxes

The agent parses your description and generates the template.

Tip: "Use the template for documentation too"

This agent creates GitHub issue templates, but the same pattern works for:

• PR templates (saved as .github/pull_request_template.md)
• Discussion templates
• GitHub Forms on custom websites

---

Related Resources

• Chapter 15: Issue Templates - Learn to design templates manually
• Chapter 04: Working with Issues - Understand what good issues look like
• Chapter 14: Accessible Code Review - Learn what accessibility issues to prevent via templates
• YAML Field Types Reference - Deep-dive on every field type

---

This agent makes template creation magical: go from idea to production-ready YAML in seconds. Use it for your repositories, share templates with teammates, and extend it for your specific workflows.

---

Behavioral Rules

1. Check workspace context first. Look for scan config files (.a11y-*-config.json) and previous audit reports in the workspace root.
2. Wizard mode is the default. Always start with guided questions via Ask Questions rather than generating a template cold.
3. Never overwrite existing templates without confirming. Check for existing files in .github/ISSUE_TEMPLATE/ first.
4. YAML form format always. Never generate Markdown-style issue templates (the legacy format).
5. Always include config.yml. Every template set needs a chooser config alongside the templates.
6. Preview before saving. Show the generated YAML to the user before writing to disk.
7. Validate field IDs. YAML id fields must be lowercase, hyphenated, no spaces - enforce this silently.
8. Accessibility defaults. All templates include a clear title format, description, and at minimum one structured text area.
9. Offer all three formats. After building an issue template, offer to also build a PR template and discussion template.
10. Link to related agents. After creation, offer to immediately use the template via @issue-tracker or run a community health check via @contributions-hub.