# Pf Write Example 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.

- **Type:** Skill
- **Install:** `agentstack add skill-rh-uxd-ai-helpers-pf-write-example-description`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rh-uxd](https://agentstack.voostack.com/s/rh-uxd)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rh-uxd](https://github.com/rh-uxd)
- **Source:** https://github.com/rh-uxd/ai-helpers/tree/main/plugins/patternfly/pf-workshop/skills/pf-write-example-description

## Install

```sh
agentstack add skill-rh-uxd-ai-helpers-pf-write-example-description
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PatternFly example and demo descriptions

Use this skill when a PatternFly developer needs to write or edit:

1. **Component example descriptions** – the text under each `### Example name` (h3) and above the ` ```ts file='./ExampleName.tsx' ``` ` block in `packages/react-core/src/components/*/examples/*.md`. This content appears on the **React** tab of component pages on PatternFly.org.
2. **Demo descriptions** – the text under each `### Demo name` in `packages/react-core/src/demos`. Demos appear as a separate **Demos** tab on the component/pattern page (alongside React examples, HTML, Design guidelines, and sometimes Accessibility).

Content should be clear, on-brand, and cross-linked where helpful. For **component examples**, use a concept intro only when the example introduces **unique functionality or the primary use** of the component (e.g. Basic); for **variations and follow-on examples**, jump straight to the benefit/implementation (e.g. "To remove the home link…"). See "Lead with the benefit (component examples)" below. The skill can also be used for short intros (e.g. composable blurbs under `## Examples` or an intro under `## Demos`). **Apply this skill only when the user asks** for help writing or editing example or demo descriptions; do not invoke it proactively. After completing a request, you may offer once to check the file for other opportunities.

## Who this is for

- A developer who just added a new example or demo and needs a first draft of the description.
- Anyone closing gaps where examples or demos have no description or only a heading.
- Non-writers who want a strong first draft that can be reviewed by content design later or published as-is when time is limited.

## Workflow

1. **Gather context**
   - Identify the file type: **component examples** (`.../components/*/examples/*.md`) or **demos** (`.../demos/**/*.md`), and the specific example or demo (heading + ts file).
   - Read the example’s or demo’s TSX/implementation if needed to understand what it shows and which props/features are used.
   - Read any existing description and nearby examples/demos in the same MD file for tone and length.

2. **Align with PatternFly content guidelines**
   - Call the **PatternFly MCP** to load current guidance:
     - Use `searchPatternFlyDocs` with `searchQuery: "writing"` (or `"patternfly design guidelines"` or `"content design"`) to find content design resources.
     - Use `usePatternFlyDocs` with `name: "Writing"` (or `"content design"` or the returned resource names/URLs) to fetch:
       - **Brand voice and tone** – friendly, approachable, collaborative, inventive; avoid jargon and fluff.
       - **Best practices** – clear, concise, user-focused; lead with benefit; positive, action-oriented language.
       - **PatternFly design guidelines** – present tense; second person ("you"); active voice; sentence-case headings; descriptive hyperlinks; relative URLs for PatternFly pages. (Note: bolding component names on first use applies to design guidelines pages, not example documentation—do not bold component names in example descriptions.)
       - **Accessibility and localization** – plain language, short sentences, consistent terminology.
   - Apply these when drafting or revising the example or demo description.

3. **Draft the description**
   - **For component examples:** **When the example introduces unique functionality or the primary use** (e.g. Basic): use a **concept intro sentence** ("A [component] gives users…") then **technical implementation sentence(s)**. **When the example is a variation or follow-on** (e.g. "Without home link", "With dropdown"): skip the concept intro and start with the benefit/implementation—e.g. "To remove the home link, use…" or "To add a dropdown to a breadcrumb item, use…". Always lead with the benefit in the first sentence the reader sees; keep concept and implementation in separate sentences when you use a concept intro. Do **not** bold component names in example descriptions.
   - **For demos:** Use the demo-specific structure below (opening sentence + "In this demo:" + bullet list of props/features). Mention what the demo shows and how key props or features are used.
   - In both cases: Use "you" and active voice, and be direct and concise. **Punctuation:** Avoid semicolons. Prefer commas or new sentences to join ideas. Use em dashes occasionally if they improve clarity. Use backticks for prop/attribute names (e.g. `isExpanded`). **Example and demo headings (h3):** Use sentence case—only the first word and proper nouns capitalized (e.g. "Read only", "Expanded with array", "Inline compact with truncation"). **Component names:** Do not capitalize component names unless at the beginning of a sentence. When referring to the React component in a code way, use angle-bracket form: ``. **Only mention the React component (e.g. ``) when multiple components are involved or it helps clarify the sentence**—otherwise just "use `propName`" or "set `propName`" is enough (e.g. "To reduce vertical spacing between rows, use `isCompact`." not "set `isCompact` on ``"). In running prose, use lowercase: "the page component," "the notification drawer."
   - Add **cross-links** only when **directly relevant**—e.g. when referencing a specific example of another component, or when the reader would likely want to cross-check. Generally, linking to other components or patterns mentioned in the description is usually relevant. When building component links:
     - **Nested components**: If the target component’s MD file has a `subsection` in its frontmatter, use `/components//` (e.g. Form with `subsection: forms` → `/components/forms/form`). Otherwise use `/components/` (e.g. `/components/button`, `/components/card`).
     - Use `[Component label](/components/...)` or `/components/.../design-guidelines` when pointing to design/usage.
     - **Pattern**: `[Pattern label](/patterns/pattern-name)`.
     - **Same-page example**: `[link text](#anchor)`. Anchor = heading text lowercased, spaces to hyphens (e.g. `#selectable`, `#cards-as-tiles`).
     - **Content design**: `/content-design/overview` as a generic landing, or specific paths like `/content-design/writing-guides/tooltips`. Paths here can be less consistent; use overview when unsure.
     - **Foundations and styles**: e.g. `/foundations-and-styles/iconography`, `/foundations-and-styles/design-tokens/overview`.
   - Use **relative** paths only; use descriptive link text (not "click here").

### Lead with the benefit (component examples)

**When to use a concept intro:** If the example is the **first or Basic one** and introduces what the component is, use a concept intro. Sometimes you’ll also want a concept intro for a **later example** when there are **complex implementation details** to share—that’s an option when it helps the reader.

**When to skip the concept intro:** For **variations and follow-on examples** (e.g. "Without home link", "With heading", "With dropdown"), **jump straight to the benefit/implementation**. Start with "To [do x], use…" or "To [achieve y],…" so the reader still sees the outcome first, but don’t repeat what the component is.

**When in doubt:** Prefer the shorter description and one clear benefit sentence.

**With concept intro** (e.g. Basic / primary use):

1. **Concept intro sentence:** What the component displays or does (e.g. "A basic data list displays a structured set of items, each with one or more cells in a row." or "A back to top component gives users a quick way to return to the top of a long page.")
2. **Optional component structure sentence(s):** When it helps clarify, describe the hierarchy using `` (e.g. "A `` includes a `` containing one or more ``.")
3. **Technical implementation sentence(s):** How to use props or control behavior (e.g. "In a `` you can control the layout of content by using `isFilled` and `alignRight`.") and any real-use caveats.

**Preferred example (data list Basic):**

```markdown
A basic data list displays a structured set of items, each with one or more cells in a row.

A `` includes a `` containing one or more ``. In a `` you can control the layout of content by using `isFilled` and `alignRight`.
```

**Another example (back to top):**

```markdown
A back to top component gives users a quick way to return to the top of a long page. This example sets `isAlwaysVisible` so the control is visible in the short demo. In a real page, the control should appear after the user scrolls 400px.
```

**Without concept intro** (variation / follow-on): Start with "To [benefit], use…" and **do not name the React component unless multiple components are involved or it clarifies**. Prefer "use `propName`" over "set `propName` on ``."

```markdown
To reduce vertical spacing between rows, use `isCompact`.
```

```markdown
To remove the home link from the breadcrumb, use [prop or approach].
```

Use the same "To [benefit], use…" shape for variation examples; only omit the concept intro sentence so you don’t repeat the concept on every example.

**Avoid / Prefer:**

- **Avoid:** "Use isCompact to reduce spacing." **Prefer:** "To reduce vertical spacing between rows, use `isCompact`."
- **Avoid:** "Passing `isBordered` to an Avatar will add a border." **Prefer:** "To add a border to an avatar and further separate it from the background, use `isBordered`."

### Demo description structure

For **demos**, prefer this format so readers know what the demo shows and how it’s built:

1. **Opening sentence:** Lead with what the demo shows—**vary the phrasing**. Options include a short descriptive sentence (e.g. "A basic notification drawer opens from the masthead and displays a list of notifications.") or user-focused ("You can [achieve X] by [approach]."). Avoid repeating "This demo demonstrates" across demos.
2. **"In this demo:" or "This demo includes:"** followed by a bullet list. Each item can tie a prop or feature to what it does, or describe an element in the demo:
   - "The `propName` prop is used to [effect]." / "A `ref`, which is passed to [thing] and used with the [component]'s `onExpand` callback to [effect]."
   - "[Thing] with [details], in both [state A] and [state B] states."

Example (descriptive style):

```markdown
A basic notification drawer opens from the masthead and displays a list of notifications.

This demo includes:

- A `ref`, which is passed to the notification drawer and used with the page component's `onNotificationDrawerExpand` callback to move focus into the drawer when it opens.
- Notification items with a header and body, in both "read" and "unread" states.
```

Use lowercase for component names in prose ("the page component"); use `` when referring to the React component in a code way (e.g. "pass `ref` to the `` component").

Keep bullets concise; use backticks for prop/component names. **Length:** A very simple demo may need only an opening sentence (no bullets). Other demos may have multiple sentences and lists of 5+ bullets—that’s fine. What matters is capturing the **unique aspects** of the demo, **why the demo matters**, and **what it is showing to users**. Cross-link to components or patterns when directly relevant (same rules as component examples).

4. **Present and iterate**
   - **Share the suggested description in raw markdown** (e.g. in a fenced code block or clearly formatted block) so the user can easily copy and paste. Write the example description in markdown (links, backticks for props, etc.).
   - Ask the user to either:
     - **Accept** the suggestion (then insert it into the MD file), or
     - **Request changes** by saying what they don’t like (e.g. too long, wrong emphasis, different link).
   - If they request changes, revise and show again; repeat until they accept or are satisfied.
   - Optionally, once done: "Do you want me to check this file for other opportunities?" (e.g. other examples missing descriptions). Do not over-suggest this; ask at most once per interaction.

5. **Apply the final text**
   - **Component examples:** Insert or replace the description after the `### Example name` line and before the ` ```ts file='./...' ``` ` block.
   - **Demos:** Insert or replace the description after the `### Demo name` line and before the ` ```ts file='./...' ``` ` block (demos may use `isFullscreen` on the code block).
   - **Rewriting vs updating:** If the user is **rewriting** (replacing) existing content, the new description can **override** existing content, including tables—but **make the user aware** that you removed or replaced something (e.g. "I replaced the previous paragraph and the table with the description below."). If they are **updating or adding** (not doing a full rewrite), tack the new content on where appropriate; do not replace existing prose or tables unless they asked for a rewrite.
   - If the user would like content design review, suggest they tag the content designer for review (no need to add PR labels; a brief note is enough).

## MD structure reference

**Component examples** (`packages/react-core/src/components/*/examples/*.md`):

```markdown
### Example heading

**If primary/unique (e.g. Basic):** [Concept intro: "A [component] gives users [benefit]."] [Technical implementation sentence(s).] **If variation/follow-on:** [Start with "To [benefit], use…" or "To [do x],…"; no concept intro.] Optional [cross-link](/components/other) if relevant.

```ts file='./ExampleName.tsx'
```
```

**Demos** (`packages/react-core/src/demos/**/*.md`):

```markdown
## Demos

Optional intro paragraph under ## Demos (e.g. focus management note).

### Demo heading

[Varied opening: e.g. "A basic [thing] opens from… and displays…" or "You can [xyz] by [abc]."]

This demo includes:

- [Bullet tying prop/feature to effect, or describing element.]
- [Bullet…]

```ts file='./examples/DemoName.tsx' isFullscreen
```
```

- Descriptions are optional but recommended; some examples and demos have none.
- Same-file anchors (component examples): from the exact heading text, lowercased, spaces → hyphens (e.g. "Cards as tiles" → `#cards-as-tiles`).

## Link conventions (PatternFly.org)

| Target | Path form | Example |
|--------|-----------|--------|
| Component (no subsection) | `/components/` | `/components/card`, `/components/button` |
| Component (with subsection in frontmatter) | `/components//` | `/components/forms/form`, `/components/menus/menu` |
| Component design guidelines | `/components/.../design-guidelines` | `/components/tooltip/design-guidelines` |
| Component accessibility | `/components/.../accessibility` | `/components/alert/accessibility` |
| Pattern | `/patterns/` | `/patterns/primary-detail` |
| Same-page example | `#anchor` | `#selectable`, `#cards-as-tiles` |
| Content design (generic) | `/content-design/overview` | Use when linking to content design generally |
| Content design (specific) | `/content-design/...` | `/content-design/writing-guides/tooltips` |
| Foundations and styles | `/foundations-and-styles/...` | `/foundations-and-styles/iconography`, `/foundations-and-styles/design-tokens/overview` |

Determine component paths by checking the target component’s MD frontmatter for `subsection` (e.g. `subsection: forms` → `/components/forms/form`). Design guidelines and some writing guides live in patternfly-org; the docs site exposes the paths above.

## Quality checks

Before suggesting the description:

- [ ] When in doubt, prefer the shorter description and one clear benefit sentence.
- [ ] No semicolons in descriptions. Prefer commas or new sentences (em dashes occasionally).
- [ ] Matches brand voice (friendly, clear, no jargon, "you" and active voice).
- [ ] Example and demo headings (h3) in sentence case (first word and proper nouns only). Component names: lowercase in prose unless starting a sentence; use `` when referring to the React component as code. Do not bold component names in example or demo descriptions.
- [ ] **Component examples:** Concept intro only for unique/primar

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rh-uxd](https://github.com/rh-uxd)
- **Source:** [rh-uxd/ai-helpers](https://github.com/rh-uxd/ai-helpers)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-rh-uxd-ai-helpers-pf-write-example-description
- Seller: https://agentstack.voostack.com/s/rh-uxd
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.