diff --git a/.claude/skills/README.md b/.claude/skills/README.md index f18bde6e..a2da7a40 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -20,6 +20,7 @@ Specialized knowledge for AI agents working on Video.js 10. | Committing / creating PRs | `git` or `/commit-pr` | | Reviewing branch changes | `/review-branch` | | Analyzing GitHub issues | `/gh-issue` | +| Creating GitHub issues | `/create-issue` | | Updating AI docs | `/claude-update` | | Creating new skills | `/create-skill` | @@ -32,6 +33,7 @@ Specialized knowledge for AI agents working on Video.js 10. | [claude-update](claude-update/SKILL.md) | Update CLAUDE.md and skills when introducing new patterns | No | | [commit-pr](commit-pr/SKILL.md) | Commit changes and create/update PRs with conventions | No | | [component](component/SKILL.md) | Build headless UI components — compound patterns, state, styling | Yes | +| [create-issue](create-issue/SKILL.md) | Create GitHub issues with consistent formatting and conventions | No | | [create-skill](create-skill/SKILL.md) | Create new skills with proper structure and conventions | No | | [design](design/SKILL.md) | Write Design Docs — decisions you own, component specs, feature designs| No | | [api-reference](api-reference/SKILL.md) | Scaffold component API reference pages | No | diff --git a/.claude/skills/commit-pr/SKILL.md b/.claude/skills/commit-pr/SKILL.md index 39a3dd76..928bd587 100644 --- a/.claude/skills/commit-pr/SKILL.md +++ b/.claude/skills/commit-pr/SKILL.md @@ -106,9 +106,19 @@ Based on the changes and `git` skill conventions: - **Existing PR (updated)**: "Updated PR #123: " - **New PR**: "Created PR #123: " +## Writing Clear PR Descriptions + +A reviewer should understand the PR in 30 seconds. Apply the same rigor as issue bodies: + +- **Why over what** -- explain motivation, not mechanics. The diff shows what changed. +- **Be concise** -- cut filler. Every sentence should carry information. +- **No file lists** -- reviewers see the diff. Describe behavior changes. +- **Collapse details** -- use `
` for implementation notes, tradeoffs, or architecture decisions that only some reviewers need. +- **Sections must earn their place** -- omit Testing if covered by existing tests with nothing to add. Omit Changes if the summary says it all. +- **Don't repeat the title** in the summary. + ## Important - Always stage ALL changes with `git add -A` -- Always check for existing PR before creating — avoid duplicate PRs +- Always check for existing PR before creating -- avoid duplicate PRs - Prefer `gh` CLI for GitHub operations; fallback to MCP tools if `gh` unavailable -- Follow PR description principles: why over what, concise, no file lists diff --git a/.claude/skills/create-issue/SKILL.md b/.claude/skills/create-issue/SKILL.md new file mode 100644 index 00000000..d79673f1 --- /dev/null +++ b/.claude/skills/create-issue/SKILL.md @@ -0,0 +1,162 @@ +--- +name: create-issue +description: >- + Create GitHub issues with consistent title casing, type prefixes, labels, + and body structure for the videojs/v10 repo. Use when filing bugs, requesting + features, or creating any ticket/issue. Triggers: "create issue", "new issue", + "file issue", "open issue", "file bug", "request feature", "create ticket", + "new ticket", "file ticket", "open ticket". +allowed-tools: Bash(gh:*), Read, Glob, Grep, question +context: fork +--- + +# Create Issue + +Create GitHub issues with consistent formatting for the videojs/v10 repo. + +## Usage + +``` +/create-issue [description] +``` + +- `description` (optional): Brief description of the issue to create. If omitted, will prompt interactively. + +## Arguments + +$ARGUMENTS + +## Conventions + +### Title Format + +**`Type: Title Case Description`** + +Use Title Case for the description portion. The type prefix is followed by a colon and space. + +| Prefix | When to Use | Example | +| ---------------- | ----------------------------------------------------- | ------------------------------------------------ | +| `Feature:` | New capability or behavior | Feature: Add OAuth Support | +| `Bug:` | Something broken or not working as expected | Bug: Playback Stalls on iOS Safari | +| `Docs:` | Documentation additions or improvements | Docs: Add Getting Started Guide | +| `Architecture:` | Internal structure, design patterns, core refactoring | Architecture: Redesign State Management Layer | +| `Chore:` | Maintenance, deps, tooling, CI | Chore: Upgrade Vitest to v3 | +| `Design:` | Design docs, component specs, visual design | Design: Component Spec for Slider | + +**Not** conventional commit prefixes (`feat:`, `fix:`, `docs:`) — those are for commits only. + +### Labels + +Use labels instead of GitHub issue types (Bug/Task/Enhancement). **Always use existing repo labels -- never create new ones.** Run `gh label list --repo videojs/v10` if unsure what exists. Prefer no label over inventing one. + +**Domain:** `api`, `a11y`, `components`, `docs`, `dx`, `i18n`, `media`, `skin`, `store`, `types` + +**Package:** `pkg:core`, `pkg:html`, `pkg:react`, `pkg:utils`, `pkg:store`, `pkg:dom`, `pkg:icons` + +**Area:** `build`, `cli`, `compiler`, `errors`, `examples`, `perf`, `site`, `test`, `workspace` + +**Other:** `feature`, `planning`, `needs discussion`, `good first issue`, `epic` + +**Rules:** +- Apply 1-3 labels -- don't over-label +- Check labels on related/cross-referenced issues for consistency +- If no existing label fits, leave it unlabeled for human triage + +### Body + +**Goal:** A reader should understand what the issue tracks or solves in 30 seconds. + +**Default to a single section** -- most issues need only a Description. Every additional section must earn its place by adding communication value the description alone can't provide. + +**Tailor content to issue type:** + +- **Bug** -- Describe the broken behavior and expected behavior. Include reproduction steps only if non-obvious. +- **Feature** -- What the capability is and why it's needed. +- **Architecture / Design** -- What API surface or internal pattern is affected and the problem with the current approach. +- **Docs / Chore** -- What needs to change and why. + +**Structure:** + +```markdown +[1-3 paragraphs: what this issue tracks and why it matters] +``` + +If -- and only if -- the issue benefits from it, add additional sections: + +```markdown +## Context + +[Links to Slack threads, related issues, prior art -- only when background isn't obvious] + +## Tasks + +- [ ] Task 1 +- [ ] Task 2 +``` + +**Rules:** +- Be concise. Cut filler. Every sentence should carry information. +- Don't repeat the title in the body. +- Omit sections that add no value -- no empty headers, no placeholder text. +- Task lists only when scope is well-defined and breakdown aids tracking. + +## Your Tasks + +### Step 1: Gather Information + +If $ARGUMENTS provides enough detail, extract: +1. **Type** — Which prefix applies (Feature, Bug, Docs, Architecture, Chore, Design) +2. **Title** — Short, descriptive, Title Case +3. **Description** — The what and why +4. **Labels** — 1-3 relevant labels + +If details are missing, use the `question` tool to ask the user. + +### Step 2: Format Title + +Construct the title as `Type: Title Case Description`. + +**Title Case rules:** +- Capitalize the first and last word +- Capitalize all major words (nouns, verbs, adjectives, adverbs) +- Lowercase articles (a, an, the), conjunctions (and, but, or), and short prepositions (in, on, at, to, for, of, with) unless they are the first or last word + +### Step 3: Compose Body + +Write the body following the body conventions. Default to a single description paragraph. Only add Context or Tasks sections if they genuinely improve communication. + +### Step 4: Confirm with User + +Before creating, show the user: +- Full title +- Labels +- Body preview + +Ask for confirmation using the `question` tool. + +### Step 5: Create Issue + +```bash +gh issue create --repo videojs/v10 \ + --title "Type: Title Case Description" \ + --label "label1,label2" \ + --body "body content" +``` + +Use a HEREDOC for the body to preserve formatting: + +```bash +gh issue create --repo videojs/v10 \ + --title "Feature: Add OAuth Support" \ + --label "feature,api" \ + --body "$(cat <<'EOF' +## Description + +... +EOF +)" +``` + +### Step 6: Report + +Output the created issue URL. diff --git a/.claude/skills/review-branch/SKILL.md b/.claude/skills/review-branch/SKILL.md index 7b187348..50ca5be4 100644 --- a/.claude/skills/review-branch/SKILL.md +++ b/.claude/skills/review-branch/SKILL.md @@ -5,6 +5,7 @@ description: >- Triggers: "review branch", "review changes", "code review". allowed-tools: Bash(git:*), Bash(gh:*), Glob, Grep, Read, mcp__github__* agent: plan +context: fork --- # Branch Review