patternfly · jpuzz0 · May 13, 2026
diff --git a/CONTRIBUTING-SKILLS.md b/CONTRIBUTING-SKILLS.md
@@ -115,6 +115,44 @@ Use the `pf-` prefix on skill and agent names that are **PatternFly-specific**.
 - Skill directory: `skills/pf-unit-test-generator/SKILL.md` with `name: pf-unit-test-generator`
 - Agent file: `agents/pf-coding-standards.md` with `name: pf-coding-standards`
 
+## Writing descriptions
+
+Every skill and agent needs a `description` in its frontmatter. This description is how the AI decides whether to load the skill — it's the single most important line in your SKILL.md.
+
+### Formula
+
+**[Action verb] [what it does]. [Use when + trigger contexts.]**
+
+### Rules
+
+1. **Start with an action verb** — Audit, Generate, Scan, Create, Validate, Find, Recommend. Not "Guide for," "Performs," "Enables," "A tool that."
+2. **One sentence for what it does** — the capability, not the implementation.
+3. **One sentence for when to use it** — "Use when" followed by 2-3 trigger scenarios separated by commas or "or."
+4. **No keyword lists** — the AI handles semantic matching. Don't pad with synonyms.
+5. **Front-load the key use case** — descriptions longer than 250 characters are truncated in the skill listing.
+
+### Examples
+
+**Good:**
+```
+description: Audit focus traps, restoration, and screen reader announcements. Use when building modals, dialogs, or wizards that manage focus programmatically.
+```
+
+**Good:**
+```
+description: Generate unit tests for React components. Use when creating new components, adding test coverage, or refactoring existing tests.
+```
+
+**Bad — starts with a weak verb:**
+```
+description: A comprehensive guide for PatternFly component structure auditing and debugging.
+```
+
+**Bad — keyword stuffing:**
+```
+description: Tool for testing, unit testing, component testing, React testing, PatternFly testing, jest testing.
+```
+
 ## Step 6: Contribute it
 
 Once you're happy with the skill:
@@ -135,7 +173,7 @@ For guidance on writing effective skills — structure, descriptions, examples,
 
 In addition to the skill-creator guidance, skills in this repo must follow these rules:
 
-- **Frontmatter is required** with `name` and `description`. The `name` must match the directory name. The `description` should include trigger contexts (e.g., "Use when...") since the AI decides whether to load the skill based on the description alone. Front-load the key use case — descriptions longer than 250 characters are truncated in the skill listing.
+- **Frontmatter is required** with `name` and `description`. The `name` must match the directory name. See [Writing descriptions](#writing-descriptions) for the description formula.
 - Add `disable-model-invocation: true` if your skill has side effects (creates issues, posts comments, deploys)
 - **Describe outcomes, not implementation** — tell the AI what to accomplish, not how to do it. The AI already knows how to use `git`, `gh`, `grep`, etc.
 - **Skills must be tool-agnostic** — they run in both Claude Code and Cursor. Avoid referencing a specific tool (e.g., use "Assistant:" instead of "Claude:" in examples).

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -29,17 +29,7 @@ Create a new plugin when your contribution represents a distinct domain that doe
 
 ### Plugin naming standard
 
-Plugin names must tell a user exactly what the plugin helps them do. Someone browsing the marketplace should understand what they're installing without clicking through.
-
-Ask: *"If someone sees this name in a list, do they know what they're installing?"*
-
-| Good | Why | Bad | Why |
-|------|-----|-----|-----|
-| `design-foundations` | Specific — tokens, icons, colors, spacing | `styling` | Vague — styling what? |
-| `issue-management` | Clear action — manages issues | `workflow` | Could mean anything |
-| `react` | Universal tech domain | `frontend` | Too broad |
-
-It's fine to create a plugin with only 1-2 skills if it represents a distinct domain. The taxonomy should reflect where the project is going, not just where it is today. Coordinate via an issue before creating a new plugin.
+Plugin names must tell a user what the plugin helps them do. See [CONTRIBUTING-SKILLS.md](CONTRIBUTING-SKILLS.md#plugin-naming-standard) for naming guidelines and examples. Coordinate via an issue before creating a new plugin.
 
 ### Steps
 
@@ -61,8 +51,10 @@ It's fine to create a plugin with only 1-2 skills if it represents a distinct do
 
 ### Skills vs Agents
 
-- **Skills** (`skills/your-skill/SKILL.md`) — tasks that produce a result. Use this for most contributions.
-- **Agents** (`agents/your-agent.md`) — domain knowledge the AI follows. Use for standards and guidelines.
+- **Skills** (`skills/your-skill/SKILL.md`) — tasks that produce a result. Most contributions are skills.
+- **Agents** (`agents/your-agent.md`) — domain knowledge the AI follows automatically.
+
+See [CONTRIBUTING-SKILLS.md](CONTRIBUTING-SKILLS.md#skill-vs-agent) for guidance on which to use.
 
 ## Adding Documentation
 

diff --git a/PLUGINS.md b/PLUGINS.md
@@ -28,13 +28,13 @@ Design foundation reference and auditing — tokens, icons, colors, spacing
 
 | Skill | Description |
 |-------|-------------|
-| `css-var-analyzer` | Analyze CSS custom property usage, redefinitions, and naming patterns in PatternFly SCSS components. |
-| `icon-finder` | Find icons from the Red Hat Design System (@rhds/icons) by use case. |
-| `pf-ai-experience-patterns` | Apply Red Hat's AI design language for AI-powered demos and features. |
-| `pf-analyze-modifiers` | Find, list, and summarize PatternFly component modifiers (pf-m- classes) across the codebase. |
-| `pf-class-migration-scanner` | Scans for legacy PatternFly class usage and recommends PF6-safe replacements. |
-| `pf-raw-colors-scan` | Analyze the provided code to find any raw color values assigned to styling properties. |
-| `pf-token-auditor` | Validate and bridge Figma design styles to PatternFly 6 design tokens. |
+| `css-var-analyzer` | Analyze --pf- CSS custom property usage and naming patterns in PatternFly SCSS. |
+| `icon-finder` | Find Red Hat Design System icons (@rhds/icons) by keyword or use case with visual previews. |
+| `pf-ai-experience-patterns` | Apply Red Hat's AI design language to AI-powered features — chatbots, assistants, generation UIs. |
+| `pf-analyze-modifiers` | Analyze PatternFly modifier class (pf-m-*) usage across SCSS files and generate usage reports. |
+| `pf-class-migration-scanner` | Scan code for legacy PatternFly CSS classes and recommend PF6-safe replacements. |
+| `pf-raw-colors-scan` | Find raw color values (hex, rgb, hsl) in code and suggest PatternFly design token replacements. |
+| `pf-token-auditor` | Audit designs against the PatternFly 6 token architecture and bridge Figma styles to PF semantic tokens. |
 | `pf-tokens` | Build CSS design tokens for PatternFly core and copy them to the PatternFly repository. |
 
 
@@ -46,10 +46,10 @@ Figma design review, diffing, and asset identification
 
 | Skill | Description |
 |-------|-------------|
-| `figma-changes` | Identify Figma design changes and generate code update checklists. |
-| `figma-icon-finder` | Identifies PatternFly icons used in Figma mockups and provides the correct import statements for React components. |
-| `pf-compliance-checker` | Check Figma designs against PatternFly v6 design system standards. |
-| `pf-design-mode` | Create and edit Figma design files using the Figma MCP workflow with PatternFly-approved libraries only. |
+| `figma-changes` | Diff Figma designs to identify what changed and generate code update checklists. |
+| `figma-icon-finder` | Identify PatternFly icons in Figma mockups and provide the correct React import statements. |
+| `pf-compliance-checker` | Check Figma designs against PatternFly v6 standards for colors, typography, spacing, and component usage. |
+| `pf-design-mode` | Create and edit Figma design files using PatternFly-approved component libraries. |
 
 
 <br>
@@ -60,11 +60,11 @@ Issue creation, tracking, and cross-project coordination
 
 | Skill | Description |
 |-------|-------------|
-| `duplicate-epic` | Use when `/duplicate-epic <issue> <feature>` should clone a Jira Epic, Story, or Bug into the PF project, resolve non-epic inputs to their parent epic, link back to the source, and attach the new epic to a PF feature. |
-| `pf-bug-triage` | Performs preliminary triage of opened issues marked as bugs. |
-| `pf-create-issue` | Create GitHub issues for PatternFly repositories with smart templates, followup tracking, and duplicate detection. |
-| `quarterly-initiative-report` | Generate comprehensive quarterly Jira status reports with progress tracking, RAG assessment, blocker identification, cross-project duplicate link analysis, and Q+1 recommendations. |
-| `summarize-jira-issues` | Summarize Jira sprint issues and contributions for the current user. |
+| `duplicate-epic` | Clone a Jira epic from another project into the PF Jira space with back-links and feature attachment. |
+| `pf-bug-triage` | Triage PatternFly bug reports — assess completeness, suggest fixes, identify affected components, and recommend assignees. |
+| `pf-create-issue` | Create well-structured GitHub issues for PatternFly repositories with templates, followup tracking, and duplicate detection. |
+| `quarterly-initiative-report` | Generate quarterly Jira status reports with RAG assessment, blocker tracking, and next-quarter recommendations. |
+| `summarize-jira-issues` | Summarize your current sprint workload from Jira — assigned issues, contributor roles, and priorities. |
 
 
 <br>
@@ -75,19 +75,19 @@ React component development — coding standards, testing, and structure
 
 | Skill | Description |
 |-------|-------------|
-| `pf-component-structure` | Guide for PatternFly React component structure — audits, correct nesting, and layout debugging. |
-| `pf-import-checker` | Audits and fixes PatternFly import paths, with emphasis on charts, chatbot, and component-groups. |
-| `pf-library-test-writer` | Write unit tests for contributors to PatternFly libraries (patternfly-react, patternfly-chatbot, etc.), not for consumers of PatternFly components. |
+| `pf-component-structure` | Audit PatternFly React component nesting, wrapper hierarchies, and layout structure. |
+| `pf-import-checker` | Audit and fix invalid PatternFly import paths across packages. |
+| `pf-library-test-writer` | Write unit tests for PatternFly library internals using mock-based isolation. |
 | `pf-project-scaffolder` | Scaffolds PatternFly React projects with PF6-safe dependencies, imports, and starter layout. |
 | `pf-prototype-mode` | Enable prototype mode for React apps (grayscale + banner) |
-| `pf-unit-test-generator` | Generate a comprehensive unit test file for a given React component |
-| `write-example-description` | Helps PatternFly developers write and refine example descriptions and demo descriptions for PatternFly.org. |
+| `pf-unit-test-generator` | Generate a unit test file for a React component using Testing Library. |
+| `write-example-description` | Write and refine example descriptions for PatternFly.org component and demo pages. |
 
 | Agent | Description |
 |-------|-------------|
 | `component-structure-audit` | PatternFly React structural composition rules — required hierarchies, wrapper components, and props-vs-children patterns. |
-| `pf-coding-standards` | PatternFly React development standards. |
-| `pf-unit-test-standards` | PatternFly React unit testing standards. |
+| `pf-coding-standards` | PatternFly React coding standards — import patterns, component composition, token usage, and style conventions. |
+| `pf-unit-test-standards` | PatternFly React testing standards — RTL patterns, mock boundaries, coverage expectations, and assertion style. |
 
 
 <br>
@@ -98,9 +98,9 @@ Release versioning, dependency analysis, and repository health
 
 | Skill | Description |
 |-------|-------------|
-| `analytics-repo-pruning` | Flags archived or inactive Git repositories listed in PatternFly Analytics repos.json so entries can be pruned. |
+| `analytics-repo-pruning` | Flag archived or inactive repos in PatternFly Analytics repos.json for removal. |
 | `dependency-recommender` | Analyzes the project's manifests and code patterns, then recommends NPM or other dependencies that would reduce complexity, increase stability, and improve reusability—with a short rationale per recommendation. |
-| `pf-org-version-update` | Updates the patternfly-org repo for a new PatternFly release or release candidate. |
+| `pf-org-version-update` | Update patternfly-org for a new PatternFly release — resolve versions, update package.json and versions.json, and provide build steps. |
 | `semantic-release-troubleshooting` | Diagnose and fix semantic-release issues when a specific version is not being released. |
 | `summarize-pr-reviews` | Summarize GitHub pull requests awaiting review from the current user. |
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -7,7 +7,6 @@ If you discover a security vulnerability in this repository, please report it re
 **Do not open a public issue for security vulnerabilities.**
 
 - **GitHub:** Use [private vulnerability reporting](https://github.com/patternfly/ai-helpers/security/advisories/new)
-- **GitLab:** Open a confidential issue
 
 ## Scope
 

diff --git a/plugins/design-foundations/skills/css-var-analyzer/SKILL.md b/plugins/design-foundations/skills/css-var-analyzer/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: css-var-analyzer
-description: Analyze CSS custom property usage, redefinitions, and naming patterns in PatternFly SCSS components. Use when auditing --pf- variables, debugging missing definitions, tracing SCSS variable cascades, or finding unused CSS custom properties.
+description: Analyze --pf- CSS custom property usage and naming patterns in PatternFly SCSS. Use when auditing variable definitions, debugging missing tokens, or finding unused custom properties.
 ---
 
 # CSS Variable Analyzer

diff --git a/plugins/design-foundations/skills/icon-finder/SKILL.md b/plugins/design-foundations/skills/icon-finder/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: icon-finder
-description: Find icons from the Red Hat Design System (@rhds/icons) by use case. Searches the Red Hat Icons demo site by keyword, returns matching icon names with a visual HTML preview for comparison. Use when the user asks to find an icon, search for an icon by purpose, pick an icon for a UI, or get icon options for a use case.
+description: Find Red Hat Design System icons (@rhds/icons) by keyword or use case with visual previews. Use when choosing an icon for a UI element or looking up available icons.
 ---
 
 # Icon Finder (Red Hat Icons)

diff --git a/plugins/design-foundations/skills/pf-ai-experience-patterns/SKILL.md b/plugins/design-foundations/skills/pf-ai-experience-patterns/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-ai-experience-patterns
-description: Apply Red Hat's AI design language for AI-powered demos and features. Use when user mentions AI experience, chatbots, virtual assistants, AI generation, or product prototypes. Proactively applies even without explicit request.
+description: Apply Red Hat's AI design language to AI-powered features — chatbots, assistants, generation UIs. Use when building AI experiences that should follow Red Hat brand and UX patterns.
 ---
 
 # Red Hat AI Experience Design Patterns

diff --git a/plugins/design-foundations/skills/pf-analyze-modifiers/SKILL.md b/plugins/design-foundations/skills/pf-analyze-modifiers/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-analyze-modifiers
-description: Find, list, and summarize PatternFly component modifiers (pf-m- classes) across the codebase. Use when analyzing component styling patterns, documenting modifier usage, or auditing CSS consistency.
+description: Analyze PatternFly modifier class (pf-m-*) usage across SCSS files and generate usage reports. Use when documenting modifier patterns, auditing CSS consistency, or planning refactors.
 ---
 
 # Analyze Modifiers

diff --git a/plugins/design-foundations/skills/pf-class-migration-scanner/SKILL.md b/plugins/design-foundations/skills/pf-class-migration-scanner/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-class-migration-scanner
-description: Scans for legacy PatternFly class usage and recommends PF6-safe replacements. Use when modernizing older PatternFly codebases.
+description: Scan code for legacy PatternFly CSS classes and recommend PF6-safe replacements. Use when upgrading from PF4/PF5 or auditing a codebase for deprecated class names.
 ---
 
 # PF Class Migration Scanner

diff --git a/plugins/design-foundations/skills/pf-raw-colors-scan/SKILL.md b/plugins/design-foundations/skills/pf-raw-colors-scan/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-raw-colors-scan
-description: "Analyze the provided code to find any raw color values assigned to styling properties. Flag these values as technical debt and suggest their replacement with design tokens."
+description: Find raw color values (hex, rgb, hsl) in code and suggest PatternFly design token replacements. Use when auditing stylesheets for hardcoded colors or enforcing token compliance.
 ---
 
 ### Role

diff --git a/plugins/design-foundations/skills/pf-token-auditor/SKILL.md b/plugins/design-foundations/skills/pf-token-auditor/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-token-auditor
-description: Validate and bridge Figma design styles to PatternFly 6 design tokens. Use when auditing Figma designs against PatternFly tokens, validating token naming, translating Figma styles to composite tokens, or when the user mentions "token validation", "token audit", "design tokens", "Figma audit", "Figma variables", "token bridge", or "PF tokens".
+description: Audit designs against the PatternFly 6 token architecture and bridge Figma styles to PF semantic tokens. Use when validating token usage, mapping Figma variables to PF tokens, or checking designs for token compliance.
 disable-model-invocation: true
 ---
 

diff --git a/plugins/design-foundations/skills/pf-tokens/SKILL.md b/plugins/design-foundations/skills/pf-tokens/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-tokens
-description: Build CSS design tokens for PatternFly core and copy them to the PatternFly repository.
+description: Build CSS design tokens for PatternFly core and copy them to the PatternFly repository. Use when regenerating tokens after design changes or during release preparation.
 ---
 
 Build CSS design tokens for PatternFly core and move them to the PatternFly repository.

diff --git a/plugins/figma/skills/figma-changes/SKILL.md b/plugins/figma/skills/figma-changes/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: figma-changes
-description: Identify Figma design changes and generate code update checklists. Use when the user asks to "check Figma updates", "track design changes", "what changed in Figma", "create changelog from Figma", or "what code needs updating based on Figma".
+description: Diff Figma designs to identify what changed and generate code update checklists. Use when syncing code with updated designs or reviewing what changed between iterations. Requires Figma MCP.
 version: 3.1.0
 ---
 

diff --git a/plugins/figma/skills/figma-icon-finder/SKILL.md b/plugins/figma/skills/figma-icon-finder/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: figma-icon-finder
-description: Identifies PatternFly icons used in Figma mockups and provides the correct import statements for React components. Use when given a Figma screenshot or URL and the user needs to know which PatternFly icons to import.
+description: Identify PatternFly icons in Figma mockups and provide the correct React import statements. Use when implementing a design and you need the right icon imports. Requires Figma MCP.
 argument-hint: "[path/to/figma-screenshot.png] or [figma-url] or use @file for autocomplete"
 ---
 

diff --git a/plugins/figma/skills/pf-compliance-checker/SKILL.md b/plugins/figma/skills/pf-compliance-checker/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-compliance-checker
-description: Check Figma designs against PatternFly v6 design system standards. Use when a user provides a Figma URL and wants to validate compliance with PatternFly colors, typography, spacing, components, and UX patterns.
+description: Check Figma designs against PatternFly v6 standards for colors, typography, spacing, and component usage. Use when validating a design for PF compliance before handoff. Requires Figma MCP.
 ---
 
 # PatternFly Compliance Checker

diff --git a/plugins/figma/skills/pf-design-mode/SKILL.md b/plugins/figma/skills/pf-design-mode/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-design-mode
-description: Create and edit Figma design files using the Figma MCP workflow with PatternFly-approved libraries only. Use when the user asks to build, update, restyle, or restructure Figma frames/components and wants write operations.
+description: Create and edit Figma design files using PatternFly-approved component libraries. Use when building, updating, or restructuring Figma frames and components. Requires Figma MCP.
 disable-model-invocation: true
 ---
 

diff --git a/plugins/issue-management/skills/duplicate-epic/SKILL.md b/plugins/issue-management/skills/duplicate-epic/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: duplicate-epic
-description: Use when `/duplicate-epic <issue> <feature>` should clone a Jira Epic, Story, or Bug into the PF project, resolve non-epic inputs to their parent epic, link back to the source, and attach the new epic to a PF feature.
+description: Clone a Jira epic from another project into the PF Jira space with back-links and feature attachment. Use when duplicating COST or cross-project epics into PF for tracking.
 disable-model-invocation: true
 ---