~/.claude/skills/github-issue-from-templates/
  SKILL.md                    # This file — generic workflow engine
  references/
    schema.json               # JSON Schema for template config files
    settings-schema.json      # JSON Schema for settings.json

~/.claude/configs/github-issue-from-templates/
  settings.json               # Storage mode config — created on first run
  *.json                      # Template configs (local mode only) — user-managed, survives skill updates

<owner>/<repo>/<path>/        # Template configs (GitHub mode) — stored in a GitHub repo
  *.json

Why a separate directory? The skill installation directory (

~/.claude/skills/...

) is replaced on

npx skills update

. Storing template configs in

~/.claude/configs/github-issue-from-templates/

(local mode) or a GitHub repo (GitHub mode) keeps them safe across updates. The

settings.json

file always lives locally since it tells the skill where to find configs.

1. GitHub MCP (preferred): Check if the GitHub MCP server is available by looking for MCP tools like

   get_file_contents

   or

   create_issue

   . If available, use MCP tools throughout.

2. gh

   CLI (fallback): If GitHub MCP is not available, verify the

   gh

   CLI is installed and authenticated by running

   gh auth status

   . If authenticated, use

   gh

   CLI commands throughout.
3. Neither available: Notify the user that either the GitHub MCP server or the

   gh

   CLI is required, and stop.

mcp

cli

Note: When using GitHub repo storage, the same detected method is used for additional operations: listing directory contents, reading files, creating/updating files, and optionally creating repositories.

1. Check if

   ~/.claude/configs/github-issue-from-templates/settings.json

   exists.
2. If it exists: Read it, validate against

   references/settings-schema.json

   , and resolve the storage mode:

   • configStorage.type === "local"

     → configs are in

     ~/.claude/configs/github-issue-from-templates/

   • configStorage.type === "github"

     → configs are in the specified GitHub repo at the configured path and branch
3. If it does not exist: Run the Setup Flow (see below).

1. Create the directory

   ~/.claude/configs/github-issue-from-templates/

   if it doesn't exist
2. Write

   settings.json

   :
   json

   {
     "configStorage": {
       "type": "local"
     }
   }

3. Offer to create a first template config

1. Ask if they have an existing repo for configs
2. If yes:
   • Gather:

     owner

     ,

     repo

     ,

     path

     (default:

     configs/github-issue-from-templates/

     ),

     branch

     (default:

     main

     )
   • Validate access by listing the directory contents using the detected GitHub method (see Loading Configs from GitHub for commands)
   • Write

     settings.json

     :
     json

     {
       "configStorage": {
         "type": "github",
         "owner": "<owner>",
         "repo": "<repo>",
         "path": "configs/github-issue-from-templates/",
         "branch": "main"
       }
     }

3. If no — help create a new repo:
   • Suggest the name

     github-issue-from-templates-configs

     (default private)
   • If MCP: Use

     create_repository

     with

     name

     ,

     private: true

     ,

     description

   • If CLI:

     gh repo create <owner>/github-issue-from-templates-configs --private --description "Template configs for github-issue-from-templates skill"

   • Create the initial directory by committing a placeholder

     README.md

     at the configured path
   • Write

     settings.json

     as above

1. Read the current

   settings.json

   to determine the current mode
2. Ask the user if they want to migrate existing configs to the new location:
   • Local → GitHub: Read each local

     .json

     config (excluding

     settings.json

     ), then commit each to the GitHub repo at the configured path
   • GitHub → Local: Fetch each

     .json

     config from GitHub, then write each to

     ~/.claude/configs/github-issue-from-templates/

3. Update

   settings.json

   with the new storage configuration
4. Confirm the switch and report how many configs were migrated

1. Load configs based on the resolved storage mode from Step 0:
   • Local: Read all

     .json

     files from

     ~/.claude/configs/github-issue-from-templates/

     , excluding

     settings.json

     . If the directory does not exist or contains no config files, offer to create a first template config.
   • GitHub: List and fetch

     .json

     files from the configured repo/path/branch (see Loading Configs from GitHub), excluding

     settings.json

     and

     README.md

     . If the directory is empty or inaccessible, notify the user and offer to add a first config.
2. For each config, compare the user's request against

   triggers.keywords

   (case-insensitive substring match) and

   triggers.description

   .
3. Single match: Proceed with that template. Confirm the selection with the user briefly (e.g., "I'll use the [template name] template.").
4. Multiple matches: Present the matching templates by

   name

   and

   description

   and ask the user to choose.
5. No match: Present all available templates by

   name

   and

   description

   and ask the user to choose.

• Title pattern: From the top-level

  title:

  field (e.g.,

  "[Issue Type] [Short descriptive title]"

  )
• Template-level labels: From the top-level

  labels:

  array
• Template-level assignees: From the top-level

  assignees:

  array
• Fields: From the

  body:

  array. For each entry:
  • Skip entries where

    type: markdown

    — these are instructional text, not fields
  • For all other entries, extract:

    • id

      — unique field identifier

    • type

      —

      dropdown

      ,

      input

      ,

      textarea

    • attributes.label

      — human-readable field name

    • attributes.description

      — help text for the field

    • attributes.options

      — available choices (for dropdowns)

    • attributes.placeholder

      — example/guidance text

    • validations.required

      — whether the field must be filled

---

• Title pattern: From

  title:

  (e.g.,

  '[A11y]: Product - Feature - Request'

  )
• Template-level labels: From

  labels:

  (may be a string or array)
• Template-level assignees: From

  assignees:

  (may be a string or array)

• Sections:

  ##

  headings define major sections
• Checkbox groups: Lines matching

  - [ ] Item text

  grouped under a heading or bold label
• Labeled fields: Bold-labeled list items like

  - **Team name:**

  under a section
• Self-verification checklists: Sections like "Yes, I have" contain items the skill should satisfy automatically

1. Pre-fill from user request: If the user already provided a value for this field in their initial message, pre-fill it and confirm during the preview step.
2. Apply defaults: Check

   config.fieldDefaults[fieldId].value

   — if present, use as the default. Also check

   config.defaults

   for matching keys.
3. Check skip conditions: Check

   config.fieldSkipConditions[fieldId]

   — if an

   onlyWhen

   condition exists and is not met, skip this field entirely.
4. Prompt if needed: If the field is required (

   validations.required: true

   ) and no value has been determined, prompt the user. Use the field's

   label

   as the question and

   description

   /

   placeholder

   as guidance.
5. Apply gathering notes: Use

   config.fieldDefaults[fieldId].gatheringNotes

   for additional guidance on how to present or gather this field.

• Be conversational — don't present a wall of questions
• Batch related questions together (e.g., ask for summary and description in one turn)
• For dropdowns, present the options from the template
• For fields with defaults, mention the default and ask if it's correct
• Skip optional fields that the user hasn't mentioned unless they're likely relevant

• Use

  config.title.override

  if present; otherwise use the pattern extracted from the template in Step 2
• Replace placeholder text with gathered field values using reasoning (e.g.,

  [Issue Type]

  → the value of the

  issue-type

  field,

  [Short descriptive title]

  → the

  summary

  field value)

• yml templates: Render each field as a

  ### Field Label

  section with the gathered value. Use

  no response

  for empty optional sections. Maintain the exact field order from the template.
• md templates: Reconstruct the markdown body with gathered values filled in. Check the appropriate checkboxes, fill in labeled fields, and include all sections.

1. Start with

   config.labels.default

2. Merge in template-level labels (from the fetched template's

   labels:

   field) — avoid duplicates
3. Apply

   config.labels.conditional

   rules:

   • keyword

     : Check if any keyword appears in the user's request (case-insensitive)

   • fieldValue

     : Check if the specified field has the specified value

   • fieldTransform

     : Derive a label from a field value using the specified transform (e.g.,

     lowercase-hyphenate

     converts "Document Status" to "document-status")
4. Apply any additional label logic defined in the template config's

   notes

issue_write

method: create
owner: <config.repository.owner>
repo: <config.repository.repo>
title: <composed title>
body: <composed body>
labels: <label array>
assignees: <assignee array>

gh issue create

gh issue create \
  --repo <config.repository.owner>/<config.repository.repo> \
  --title "<composed title>" \
  --body "<composed body>" \
  --label "<label1>" --label "<label2>" \
  --assignee "<assignee1>" --assignee "<assignee2>"

• Pass each label and assignee as a separate

  --label

  /

  --assignee

  flag
• Use a heredoc for the body if it contains special characters:
  bash

  gh issue create \
    --repo owner/repo \
    --title "Title" \
    --body "$(cat <<'EOF'
  <composed body>
  EOF
  )" \
    --label "label1" --label "label2"

• Parse the issue URL from the command output (printed to stdout on success)

• If MCP: Get the URL from the response payload (e.g.,

  html_url

  field)
• If CLI: The

  gh issue create

  command prints the issue URL to stdout

config.postCreation

config.postCreation.displayFormat

{issueNumber}

{issueUrl}

config.postCreation.additionalNotes

config.linkFormatting.rules

1. Check each rule's

   match

   description to determine if it applies
2. Apply the

   format

   specified by the matching rule
3. Use

   customText

   as link text if provided

• GitHub issue/PR URLs as list items → raw URL (no markdown wrapping) so GitHub renders title + status
• Design links → markdown link with

  (see design)

  as text
• All other links → standard markdown

  [descriptive text](url)

config.acceptanceCriteria

1. Start with

   config.acceptanceCriteria.defaultItems

   as baseline criteria
2. Ask the user for additional criteria
3. Render using

   config.acceptanceCriteria.formatting.style

   (

   checklist

   =

   - [ ] item

   ,

   bullets

   =

   - item

   )
4. Avoid the prefixes listed in

   config.acceptanceCriteria.formatting.avoidPrefixes

settings.json

references/settings-schema.json

• Notify the user that the settings file is invalid
• Show the specific validation error
• Offer to re-run the Setup Flow to create a new

  settings.json

configStorage.type === "github"

• Notify the user that the config repository could not be reached
• Suggest checking: repository existence, access permissions, branch name
• If using CLI, suggest

  gh auth status

  to verify authentication
• Offer to switch to local storage mode

.json

• Notify the user that no template configs were found
• Offer to create a first template config

• Notify the user of the failure
• Provide context about potential causes: branch protection rules, insufficient permissions, file conflicts
• If the error includes a SHA mismatch, suggest re-fetching the file and retrying
• Offer to save the config locally as a fallback

get_file_contents

gh api

• Notify the user that the template could not be fetched
• Suggest checking repository access permissions
• If using CLI, suggest running

  gh auth status

  to verify authentication
• Offer to create the issue manually without template structure

• Skip that template during selection
• Notify the user which config failed to parse

issue_write

gh issue create

1. Stop the operation immediately
2. Notify the user of the failure
3. Provide context about potential causes: authentication token issues, permissions, rate limits, invalid repository access
4. If using CLI, include the stderr output from the

   gh

   command for diagnostics
5. Offer to display the composed issue body so the user can create it manually

1. Create a new

   .json

   file in

   ~/.claude/configs/github-issue-from-templates/

2. Follow the schema defined in

   references/schema.json

3. Set

   repository.owner

   and

   repository.repo

   to the target GitHub repository
4. Set

   templateSource.path

   to the repo-relative path of the GitHub issue template
5. Set

   templateSource.format

   to

   yml

   or

   md

   based on the template type
6. Define

   triggers.keywords

   for automatic template matching
7. Add any

   fieldDefaults

   ,

   fieldSkipConditions

   , label rules, and formatting overrides
8. No changes to this SKILL.md file are needed

1. Compose the config JSON following

   references/schema.json

2. Commit the file to the configured repo:
   If MCP: Use

   create_or_update_file

   :

   owner:   <configStorage.owner>
   repo:    <configStorage.repo>
   path:    <configStorage.path>/<filename>.json
   content: <base64-encoded JSON>
   message: "Add <template-name> template config"
   branch:  <configStorage.branch>

   If CLI: Use the GitHub contents API:
   bash

   gh api repos/<owner>/<repo>/contents/<path>/<filename>.json \
     --method PUT \
     --field message="Add <template-name> template config" \
     --field branch=<branch> \
     --field content=$(echo '<JSON content>' | base64)

3. No changes to this SKILL.md file are needed

1. Fetch the current file to get its SHA:
   If MCP: Use

   get_file_contents

   — the response includes the

   sha

   field.
   If CLI:
   bash

   gh api repos/<owner>/<repo>/contents/<path>/<filename>.json?ref=<branch> --jq '.sha'

2. Update the file with the SHA included:
   If MCP: Use

   create_or_update_file

   with the

   sha

   parameter:

   owner:   <configStorage.owner>
   repo:    <configStorage.repo>
   path:    <configStorage.path>/<filename>.json
   content: <base64-encoded updated JSON>
   message: "Update <template-name> template config"
   branch:  <configStorage.branch>
   sha:     <current SHA>

   If CLI:
   bash

   gh api repos/<owner>/<repo>/contents/<path>/<filename>.json \
     --method PUT \
     --field message="Update <template-name> template config" \
     --field branch=<branch> \
     --field content=$(echo '<updated JSON>' | base64) \
     --field sha=<current SHA>

• Use

  no response

  for any section where no information was provided — never omit sections
• Include all template sections in the exact order they appear in the fetched template
• Use bullet points for lists
• Use proper markdown formatting
• Label names: lowercase with hyphens (e.g.,

  document-status

  ,

  bmt-team-2

  )