template-builder

What this skill does

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](shared-instructions.md)

**Skills:** [`github-workflow-standards`](../skills/github-workflow-standards/SKILL.md), [`github-scanning`](../skills/github-scanning/SKILL.md)

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](../../.github/agents/shared-instructions.md)

**Skills:** [`github-workflow-standards`](../../.github/skills/github-workflow-standards/SKILL.md), [`github-scanning`](../../.github/skills/github-scanning/SKILL.md)

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:**
```yaml
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:**
```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:

| Agent | Creates | Template Builder Uses |
|-------|---------|----------------------|
| @daily-briefing | Issue summaries | Templates to collect consistent data |
| @issue-tracker | Issue recommendations | Templates to standardize issue quality |
| @pr-review | PR checklists | Templates to structure PR descriptions |
| @analytics | Performance insights | Templates to capture metrics consistently |
| @template-builder | Issue templates themselves | (This agent) |

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

---

## Day 2 Amplifier: From Manual to Magical

| Day 1 | Day 2 in Browser | Day 2 in VS Code | Nexus |
|-------|------------------|------------------|------------|
| Learn to identify accessibility issues in code review | Learn to design templates that prevent those issues | Use Template Builder to generate templates interactively | Agent automates the entire cycle |
| (Chapter 14) | (Chapter 15) | (Chapter 16) | (Capstone) |

---

## 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-secur