From fa01b4929b94bc2c409ace0b21c05fd4e74189ff Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 1 Feb 2026 16:01:29 -0600 Subject: [PATCH] add helper skills --- .claude/skills/draft-changelog/SKILL.md | 7 ++ .../draft-changelog/prompts/instructions.md | 58 +++++++++++++++ .claude/skills/gh-triage/README.md | 14 ++++ .claude/skills/gh-triage/SKILL.md | 12 +++ .../skills/gh-triage/prompts/agent-prompt.md | 60 +++++++++++++++ .../skills/gh-triage/prompts/instructions.md | 74 +++++++++++++++++++ .claude/skills/release-module/README.md | 24 ++++++ .claude/skills/release-module/SKILL.md | 7 ++ .../release-module/prompts/instructions.md | 57 ++++++++++++++ .gitignore | 2 +- 10 files changed, 314 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/draft-changelog/SKILL.md create mode 100644 .claude/skills/draft-changelog/prompts/instructions.md create mode 100644 .claude/skills/gh-triage/README.md create mode 100644 .claude/skills/gh-triage/SKILL.md create mode 100644 .claude/skills/gh-triage/prompts/agent-prompt.md create mode 100644 .claude/skills/gh-triage/prompts/instructions.md create mode 100644 .claude/skills/release-module/README.md create mode 100644 .claude/skills/release-module/SKILL.md create mode 100644 .claude/skills/release-module/prompts/instructions.md diff --git a/.claude/skills/draft-changelog/SKILL.md b/.claude/skills/draft-changelog/SKILL.md new file mode 100644 index 00000000..f25f8c48 --- /dev/null +++ b/.claude/skills/draft-changelog/SKILL.md @@ -0,0 +1,7 @@ +--- +name: draft-changelog +description: Analyzes changes since the last release and generates a draft changelog entry +disable-model-invocation: true +--- + +Read `prompts/instructions.md` and execute. diff --git a/.claude/skills/draft-changelog/prompts/instructions.md b/.claude/skills/draft-changelog/prompts/instructions.md new file mode 100644 index 00000000..a9b98bb8 --- /dev/null +++ b/.claude/skills/draft-changelog/prompts/instructions.md @@ -0,0 +1,58 @@ +# Draft Changelog Execution + +## Input +Project path (or run from project root) + +## Step 1: Identify Current State +- Get the latest released tag +- Get current version +- Verify there are commits since the last release + +## Step 2: Launch Explore Agent + +Use `thoroughness: "very thorough"` to analyze all changes since the last release tag. + +**Key: For each merge commit, look up the merged PR/issue that was closed.** +- Use `gh pr view` or git commit body to find the PR number +- Read the PR description and comments to understand full context +- Don't rely solely on commit merge messages - they lack context + +**Analyze:** + +1. **All merges/commits** since the last tag +2. **For each merge, read the original PR/issue** that was closed +3. **Files changed** with statistics +4. **Categorize changes:** + - 🎁 **Features** - New functionality, new agents, new workflows + - 🐛 **Bug Fixes** - Fixed bugs, corrected issues + - ♻️ **Refactoring** - Code improvements, reorganization + - 📚 **Documentation** - Docs updates, README changes + - 🔧 **Maintenance** - Dependency updates, tooling, infrastructure + - 💥 **Breaking Changes** - Changes that may affect users + +**Provide:** +- Comprehensive summary of ALL changes with PR context +- Categorization of each change +- Identification of breaking changes +- Significance assessment (major/minor/trivial) + +## Step 3: Generate Draft Changelog + +Format: +```markdown +## v0.X.X - [Date] + +* [Change 1 - categorized by type] +* [Change 2] +``` + +Guidelines: +- Present tense ("Fix bug" not "Fixed bug") +- Most significant changes first +- Group related changes +- Clear, concise language +- For breaking changes, clearly indicate impact + +## Step 4: Present Draft + +Show the draft with current version, last tag, commit count, and options to edit/retry. diff --git a/.claude/skills/gh-triage/README.md b/.claude/skills/gh-triage/README.md new file mode 100644 index 00000000..3692e3d2 --- /dev/null +++ b/.claude/skills/gh-triage/README.md @@ -0,0 +1,14 @@ +# gh-triage + +Fetches all GitHub issues via gh CLI and uses AI agents to deeply analyze, cluster, and prioritize issues. + +## Usage + +Run from within any BMad Method repository to triage issues. + +## What It Does + +1. Fetches all open issues via `gh issue list` +2. Splits issues into batches +3. Launches parallel agents to analyze each batch +4. Generates comprehensive triage report to `_bmad-output/triage-reports/` diff --git a/.claude/skills/gh-triage/SKILL.md b/.claude/skills/gh-triage/SKILL.md new file mode 100644 index 00000000..6a6d7c83 --- /dev/null +++ b/.claude/skills/gh-triage/SKILL.md @@ -0,0 +1,12 @@ +--- +name: gh-triage +description: Fetch all GitHub issues via gh CLI and use AI agents to deeply analyze, cluster, and prioritize issues +license: MIT +disable-model-invocation: true +metadata: + author: bmad-code-org + version: "3.0.0" +compatibility: Requires gh CLI, git repository, and BMad Method with Task tool support +--- + +Read `prompts/instructions.md` and execute. diff --git a/.claude/skills/gh-triage/prompts/agent-prompt.md b/.claude/skills/gh-triage/prompts/agent-prompt.md new file mode 100644 index 00000000..5c0d7d8d --- /dev/null +++ b/.claude/skills/gh-triage/prompts/agent-prompt.md @@ -0,0 +1,60 @@ +You are analyzing a batch of GitHub issues for deep understanding and triage. + +**YOUR TASK:** +Read the issues in your batch and provide DEEP analysis: + +1. **For EACH issue, analyze:** + - What is this ACTUALLY about? (beyond keywords) + - What component/system does it affect? + - What's the impact and severity? + - Is it a bug, feature request, or something else? + - What specific theme does it belong to? + +2. **PRIORITY ASSESSMENT:** + - CRITICAL: Blocks users, security issues, data loss, broken installers + - HIGH: Major functionality broken, important features missing + - MEDIUM: Workarounds available, minor bugs, nice-to-have features + - LOW: Edge cases, cosmetic issues, questions + +3. **RELATIONSHIPS:** + - Duplicates: Near-identical issues about the same problem + - Related: Issues connected by theme or root cause + - Dependencies: One issue blocks or requires another + +**YOUR BATCH:** +[Paste the batch of issues here - each with number, title, body, labels] + +**OUTPUT FORMAT (JSON only, no markdown):** +{ + "issues": [ + { + "number": 123, + "title": "issue title", + "deep_understanding": "2-3 sentences explaining what this is really about", + "affected_components": ["installer", "workflows", "docs"], + "issue_type": "bug/feature/question/tech-debt", + "priority": "CRITICAL/HIGH/MEDIUM/LOW", + "priority_rationale": "Why this priority level", + "theme": "installation/workflow/integration/docs/ide-support/etc", + "relationships": { + "duplicates_of": [456], + "related_to": [789, 101], + "blocks": [111] + } + } + ], + "cross_repo_issues": [ + {"number": 123, "target_repo": "bmad-builder", "reason": "about agent builder"} + ], + "cleanup_candidates": [ + {"number": 456, "reason": "v4-related/outdated/duplicate"} + ], + "themes_found": { + "Installation Blockers": { + "count": 5, + "root_cause": "Common pattern if identifiable" + } + } +} + +Return ONLY valid JSON. No explanations outside the JSON structure. diff --git a/.claude/skills/gh-triage/prompts/instructions.md b/.claude/skills/gh-triage/prompts/instructions.md new file mode 100644 index 00000000..782d2326 --- /dev/null +++ b/.claude/skills/gh-triage/prompts/instructions.md @@ -0,0 +1,74 @@ +# GitHub Issue Triage with AI Analysis + +**CRITICAL RULES:** +- NEVER include time or effort estimates in output or recommendations +- Focus on WHAT needs to be done, not HOW LONG it takes +- Use Bash tool with gh CLI for all GitHub operations + +## Execution + +### Step 1: Fetch Issues +Use `gh issue list --json number,title,body,labels` to fetch all open issues. + +### Step 2: Batch Creation +Split issues into batches of ~10 issues each for parallel analysis. + +### Step 3: Parallel Agent Analysis +For EACH batch, use the Task tool with `subagent_type=general-purpose` to launch an agent with prompt from `prompts/agent-prompt.md` + +### Step 4: Consolidate & Generate Report +After all agents complete, create a comprehensive markdown report saved to `_bmad-output/triage-reports/triage-YYYY-MM-DD.md` + +## Report Format + +### Executive Summary +- Total issues analyzed +- Issue count by priority (CRITICAL, HIGH, MEDIUM, LOW) +- Major themes discovered +- Top 5 critical issues requiring immediate attention + +### Critical Issues (CRITICAL Priority) +For each CRITICAL issue: +- **#123 - [Issue Title](url)** +- **What it's about:** [Deep understanding] +- **Affected:** [Components] +- **Why Critical:** [Rationale] +- **Suggested Action:** [Specific action] + +### High Priority Issues (HIGH Priority) +Same format as Critical, grouped by theme. + +### Theme Clusters +For each major theme: +- **Theme Name** (N issues) +- **What connects these:** [Pattern] +- **Root cause:** [If identifiable] +- **Consolidated actions:** [Bulk actions if applicable] +- **Issues:** #123, #456, #789 + +### Relationships & Dependencies +- **Duplicates:** List pairs with `gh issue close` commands +- **Related Issues:** Groups of related issues +- **Dependencies:** Blocking relationships + +### Cross-Repo Issues +Issues that should be migrated to other repositories. + +For each, provide: +``` +gh issue close XXX --repo CURRENT_REPO --comment "This issue belongs in REPO. Please report at https://github.com/TARGET_REPO/issues/new" +``` + +### Cleanup Candidates +- **v4-related:** Deprecated version issues with close commands +- **Stale:** No activity >30 days +- **Low priority + old:** Low priority issues >60 days old + +### Actionable Next Steps +Specific, prioritized actions: +1. [CRITICAL] Fix broken installer - affects all new users +2. [HIGH] Resolve Windows path escaping issues +3. [HIGH] Address workflow integration bugs +etc. + +Include `gh` commands where applicable for bulk actions. diff --git a/.claude/skills/release-module/README.md b/.claude/skills/release-module/README.md new file mode 100644 index 00000000..5dbaf254 --- /dev/null +++ b/.claude/skills/release-module/README.md @@ -0,0 +1,24 @@ +# release-module + +Automates the complete release process for npm modules. + +## Usage + +Run from project root or pass project path: +``` +bmad-utility-skills:release-module +``` + +## Prerequisite + +First run `draft-changelog` to analyze changes and create a draft changelog. + +## What It Does + +1. Gets and confirms changelog entry +2. Confirms version bump type (patch/minor/major) +3. Updates CHANGELOG.md +4. Bumps version with `npm version` +5. Pushes git tag +6. Publishes to npm +7. Creates GitHub release diff --git a/.claude/skills/release-module/SKILL.md b/.claude/skills/release-module/SKILL.md new file mode 100644 index 00000000..3ba15657 --- /dev/null +++ b/.claude/skills/release-module/SKILL.md @@ -0,0 +1,7 @@ +--- +name: release-module +description: Automates the complete release process for npm modules - version bump, changelog, git tag, npm publish, GitHub release +disable-model-invocation: true +--- + +Read `prompts/instructions.md` and execute. diff --git a/.claude/skills/release-module/prompts/instructions.md b/.claude/skills/release-module/prompts/instructions.md new file mode 100644 index 00000000..b026ed2d --- /dev/null +++ b/.claude/skills/release-module/prompts/instructions.md @@ -0,0 +1,57 @@ +# Release BMad Module Execution + +## Input +Project path (or run from project root) + +## Execution Steps + +### Step 1: Get Current State +- Verify git working tree is clean +- Get latest tag and current version +- Check for unpushed commits + +### Step 2: Get Changelog Entry + +Ask the user for the changelog entry (from draft-changelog skill or manual). + +### Step 3: Confirm Changelog + +Show project name, current version, proposed next version, and changelog. Get confirmation. + +### Step 4: Confirm Version Bump Type + +Ask what type of bump: patch, minor, major, prerelease, or custom. + +### Step 5: Update CHANGELOG.md + +Insert new entry at top, commit, and push. + +### Step 6: Bump Version + +Run `npm version` to update package.json, create commit, and create tag. + +### Step 7: Push Tag + +Push the new version tag to GitHub. + +### Step 8: Publish to npm + +Publish the package. + +### Step 9: Create GitHub Release + +Create release with changelog notes using `gh release create`. + +### Step 10: Confirm Completion + +Show npm and GitHub links. + +## Error Handling + +Stop immediately on any step failure. Inform user and suggest fix. + +## Important Notes + +- Wait for user confirmation before destructive operations +- Push changelog commit before version bump +- Use explicit directory paths in commands diff --git a/.gitignore b/.gitignore index 885cb245..6af83303 100644 --- a/.gitignore +++ b/.gitignore @@ -50,7 +50,7 @@ _bmad-output .qwen .rovodev .kilocodemodes -.claude +.claude/commands .codex .github/chatmodes .github/agents