diff --git a/CONTRIBUTING-SKILLS.md b/CONTRIBUTING-SKILLS.md
index cf1cf2a..c135009 100644
--- 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
index c99263c..b0e1362 100644
--- 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
index 657af86..24a5d47 100644
--- 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
index cc112f3..cd2380e 100644
--- 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
index 70a1d7b..6956f96 100644
--- 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
index 6317d84..fa823a8 100644
--- 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
index 4c46e0f..725b2e4 100644
--- 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
index 34858e2..23bf189 100644
--- 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
index 22b7af8..783d85a 100644
--- 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
index eb1e0a2..2229e2d 100644
--- 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
index 00c4814..45494d0 100644
--- 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
index 61e38b9..aa710f1 100644
--- 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
index c828858..ea98c29 100644
--- 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
index 2d6f27d..b8c7e0a 100644
--- 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
index afd5e6e..141e50e 100644
--- 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
index d3baee8..ddf0c93 100644
--- 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
index 6b900e7..26f4210 100644
--- 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
 ---
 
diff --git a/plugins/issue-management/skills/pf-bug-triage/SKILL.md b/plugins/issue-management/skills/pf-bug-triage/SKILL.md
index 17513f0..7a349ae 100644
--- a/plugins/issue-management/skills/pf-bug-triage/SKILL.md
+++ b/plugins/issue-management/skills/pf-bug-triage/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-bug-triage
-description: Performs preliminary triage of opened issues marked as bugs. Suggests what needs to be updated to fix reported bugs, provides context for assignees, and tags the most appropriate maintainer when the issue contains questions. Use when triaging bug issues, reviewing new bug reports, or preparing issues for assignment.
+description: Triage PatternFly bug reports — assess completeness, suggest fixes, identify affected components, and recommend assignees. Use when reviewing new bug issues or preparing them for assignment.
 ---
 
 # Bug Triage
diff --git a/plugins/issue-management/skills/pf-create-issue/SKILL.md b/plugins/issue-management/skills/pf-create-issue/SKILL.md
index 4ac7178..b29d14c 100644
--- a/plugins/issue-management/skills/pf-create-issue/SKILL.md
+++ b/plugins/issue-management/skills/pf-create-issue/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-create-issue
-description: Create GitHub issues for PatternFly repositories with smart templates, followup tracking, and duplicate detection.
+description: Create well-structured GitHub issues for PatternFly repositories with templates, followup tracking, and duplicate detection. Use when filing bugs, feature requests, or cross-repo followups.
 ---
 
 # PatternFly Issue Creator
diff --git a/plugins/issue-management/skills/quarterly-initiative-report/SKILL.md b/plugins/issue-management/skills/quarterly-initiative-report/SKILL.md
index e74e186..2ffbf66 100644
--- a/plugins/issue-management/skills/quarterly-initiative-report/SKILL.md
+++ b/plugins/issue-management/skills/quarterly-initiative-report/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: quarterly-initiative-report
-description: Generate comprehensive quarterly Jira status reports with progress tracking, RAG assessment, blocker identification, cross-project duplicate link analysis, and Q+1 recommendations. Use when generating quarterly reports, tracking initiative progress, or analyzing epic completion metrics across Jira projects with labels.
+description: Generate quarterly Jira status reports with RAG assessment, blocker tracking, and next-quarter recommendations. Use when preparing quarterly initiative reviews or tracking epic progress.
 disable-model-invocation: false
 ---
 
diff --git a/plugins/issue-management/skills/summarize-jira-issues/SKILL.md b/plugins/issue-management/skills/summarize-jira-issues/SKILL.md
index d24a95f..fe62f0e 100644
--- a/plugins/issue-management/skills/summarize-jira-issues/SKILL.md
+++ b/plugins/issue-management/skills/summarize-jira-issues/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: summarize-jira-issues
-description: "Summarize Jira sprint issues and contributions for the current user. Use when the user asks to: (1) See what's left in the sprint, (2) Summarize their assigned work, (3) Prioritize sprint tasks, (4) See issues they're contributing to, or (5) Understand what to work on next. Focuses on active sprint work first, then shows contributor roles and backlog."
+description: Summarize your current sprint workload from Jira — assigned issues, contributor roles, and priorities. Use when checking what's left in the sprint or deciding what to work on next.
 ---
 
 # Summarize My Jira Issues
diff --git a/plugins/react/agents/pf-coding-standards.md b/plugins/react/agents/pf-coding-standards.md
index 1477ef3..9166e24 100644
--- a/plugins/react/agents/pf-coding-standards.md
+++ b/plugins/react/agents/pf-coding-standards.md
@@ -1,6 +1,6 @@
 ---
 name: pf-coding-standards
-description: PatternFly React development standards. Use when writing, reviewing, or refactoring PatternFly React components, layouts, or styles.
+description: PatternFly React coding standards — import patterns, component composition, token usage, and style conventions. Use when writing, reviewing, or refactoring PF React code.
 ---
 
 # PatternFly React Development Standards
diff --git a/plugins/react/agents/pf-unit-test-standards.md b/plugins/react/agents/pf-unit-test-standards.md
index af1fdef..eb97481 100644
--- a/plugins/react/agents/pf-unit-test-standards.md
+++ b/plugins/react/agents/pf-unit-test-standards.md
@@ -1,6 +1,6 @@
 ---
 name: pf-unit-test-standards
-description: PatternFly React unit testing standards. Use when writing, reviewing, or modifying unit tests for PatternFly React components.
+description: PatternFly React testing standards — RTL patterns, mock boundaries, coverage expectations, and assertion style. Use when writing or reviewing unit tests for PF components.
 ---
 
 # PatternFly React Unit Test Standards
diff --git a/plugins/react/skills/pf-component-structure/SKILL.md b/plugins/react/skills/pf-component-structure/SKILL.md
index a97068b..ec55916 100644
--- a/plugins/react/skills/pf-component-structure/SKILL.md
+++ b/plugins/react/skills/pf-component-structure/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-component-structure
-description: Guide for PatternFly React component structure — audits, correct nesting, and layout debugging. Use when building with @patternfly/react-core or @patternfly/react-table, scanning code for hierarchy violations, or fixing spacing and alignment issues.
+description: Audit PatternFly React component nesting, wrapper hierarchies, and layout structure. Use when scanning for hierarchy violations or debugging spacing caused by missing wrapper components.
 ---
 
 Use this skill when you need a **structural audit** of PatternFly usage, or when fixing layouts caused by skipped wrappers. For day-to-day composition rules while writing UI, use the **component-structure-audit** agent (react plugin) or your client’s equivalent subagent for PatternFly structure.
diff --git a/plugins/react/skills/pf-import-checker/SKILL.md b/plugins/react/skills/pf-import-checker/SKILL.md
index 1180dd6..8e31c4e 100644
--- a/plugins/react/skills/pf-import-checker/SKILL.md
+++ b/plugins/react/skills/pf-import-checker/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-import-checker
-description: Audits and fixes PatternFly import paths, with emphasis on charts, chatbot, and component-groups. Use when imports fail or PatternFly modules are unresolved.
+description: Audit and fix invalid PatternFly import paths across packages. Use when imports fail, modules are unresolved, or after upgrading PatternFly versions.
 ---
 
 # PF Import Checker
diff --git a/plugins/react/skills/pf-library-test-writer/SKILL.md b/plugins/react/skills/pf-library-test-writer/SKILL.md
index d675738..88eab38 100644
--- a/plugins/react/skills/pf-library-test-writer/SKILL.md
+++ b/plugins/react/skills/pf-library-test-writer/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-library-test-writer
-description: Write unit tests for contributors to PatternFly libraries (patternfly-react, patternfly-chatbot, etc.), not for consumers of PatternFly components. Use `unit-test-generator` for consumer application tests instead.
+description: Write unit tests for PatternFly library internals using mock-based isolation. Use when contributing tests to patternfly-react, patternfly-chatbot, or other PF library repos — not for consumer app tests.
 ---
 
 Write unit tests for components and features within PatternFly ecosystem libraries (patternfly-react, patternfly-chatbot, patternfly-virtual-assistant, and other JS/TS-based PatternFly libraries). Unlike `unit-test-generator` which tests at the network boundary, this skill **mocks child components** for unit isolation of individual library components.
diff --git a/plugins/react/skills/pf-unit-test-generator/SKILL.md b/plugins/react/skills/pf-unit-test-generator/SKILL.md
index ee7a2b2..5f11c04 100644
--- a/plugins/react/skills/pf-unit-test-generator/SKILL.md
+++ b/plugins/react/skills/pf-unit-test-generator/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-unit-test-generator
-description: Generate a comprehensive unit test file for a given React component
+description: Generate a unit test file for a React component using Testing Library. Use when adding test coverage to new or existing components.
 ---
 
 Generate a comprehensive unit test file for the given React component.
diff --git a/plugins/react/skills/write-example-description/SKILL.md b/plugins/react/skills/write-example-description/SKILL.md
index f61f9cf..715242e 100644
--- a/plugins/react/skills/write-example-description/SKILL.md
+++ b/plugins/react/skills/write-example-description/SKILL.md
@@ -1,13 +1,6 @@
 ---
 name: write-example-description
-description: >-
-  Helps PatternFly developers write and refine example descriptions and demo
-  descriptions for PatternFly.org. Covers (1) component example MD files: prose
-  under each ### heading before the ts block in
-  packages/react-core/src/components/*/examples/*.md; (2) demo MD files: prose
-  under ## Demos / ### Demo name in packages/react-core/src/demos. Uses
-  PatternFly MCP for UX writing and content guidelines, suggests cross-links,
-  and asks the user to accept or request changes. Run only when the user asks.
+description: Write and refine example descriptions for PatternFly.org component and demo pages. Use when authoring or updating the prose in PatternFly example markdown files.
 ---
 
 # PatternFly example and demo descriptions
diff --git a/plugins/repo-management/skills/analytics-repo-pruning/SKILL.md b/plugins/repo-management/skills/analytics-repo-pruning/SKILL.md
index d04681c..d806804 100644
--- a/plugins/repo-management/skills/analytics-repo-pruning/SKILL.md
+++ b/plugins/repo-management/skills/analytics-repo-pruning/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: analytics-repo-pruning
-description: Flags archived or inactive Git repositories listed in PatternFly Analytics repos.json so entries can be pruned. Use when reviewing repos.json, auditing tracked codebases, or removing stale or archived repos from analytics.
+description: Flag archived or inactive repos in PatternFly Analytics repos.json for removal. Use when auditing tracked codebases or pruning stale entries from analytics.
 ---
 
 # Analytics repo pruning
diff --git a/plugins/repo-management/skills/pf-org-version-update/SKILL.md b/plugins/repo-management/skills/pf-org-version-update/SKILL.md
index 7849ef9..1798738 100644
--- a/plugins/repo-management/skills/pf-org-version-update/SKILL.md
+++ b/plugins/repo-management/skills/pf-org-version-update/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: pf-org-version-update
-description: Updates the patternfly-org repo for a new PatternFly release or release candidate. Fetches or applies specified versions, updates package.json files and versions.json, and then provides the user with steps to run the build and regenerate screenshots locally. Use when preparing a PatternFly release, updating PF versions in this repo, or when the user asks to update patternfly-org for a new release.
+description: Update patternfly-org for a new PatternFly release — resolve versions, update package.json and versions.json, and provide build steps. Use when cutting a PF release or release candidate.
 ---
 
 # PatternFly Org Version Update