# Dita Entity Reference

> Replace HTML character entity references with Unicode equivalents for DITA compatibility. Use this skill when asked to fix entity references, replace HTML entities, or prepare files for DITA conversion.

- **Type:** Skill
- **Install:** `agentstack add skill-abhatt-rh-redhat-docs-agent-tools-dita-entity-reference`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [abhatt-rh](https://agentstack.voostack.com/s/abhatt-rh)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [abhatt-rh](https://github.com/abhatt-rh)
- **Source:** https://github.com/abhatt-rh/redhat-docs-agent-tools/tree/main/plugins/dita-tools/skills/dita-entity-reference
- **Website:** https://redhat-documentation.github.io/redhat-docs-agent-tools/

## Install

```sh
agentstack add skill-abhatt-rh-redhat-docs-agent-tools-dita-entity-reference
```

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

## About

# Entity reference transform skill

Replace unsupported HTML character entity references with their Unicode equivalents for DITA compatibility.

## Overview

This skill uses the `entity_reference.rb` Ruby script to find and replace HTML character entity references (like ` `, `—`, `©`) with their Unicode character equivalents. DITA only supports five XML entities: `&`, `<`, `>`, `'`, and `"`.

## What it transforms

### Common replacements

| Entity | Unicode | Description |
|--------|---------|-------------|
| ` ` | ` ` | Non-breaking space |
| `–` | `–` | En dash |
| `—` | `—` | Em dash |
| `…` | `…` | Horizontal ellipsis |
| `©` | `©` | Copyright |
| `®` | `®` | Registered trademark |
| `™` | `™` | Trademark |
| `→` | `→` | Right arrow |
| `←` | `←` | Left arrow |

### Supported entity categories

- Spaces and breaks
- Dashes and hyphens
- Quotation marks
- Punctuation
- Currency symbols
- Math and symbols
- Arrows
- Greek letters
- Accented characters

## Usage

When the user asks to fix entity references:

1. Identify the target folder or file containing AsciiDoc content
2. Find all `.adoc` files in the target location
3. Run the Ruby script against each file:
   ```bash
   ruby ${CLAUDE_SKILL_DIR}/scripts/entity_reference.rb 
   ```
4. Report the number of replacements made and any unknown entities found

### Dry run mode

To preview changes without modifying files:

```bash
ruby ${CLAUDE_SKILL_DIR}/scripts/entity_reference.rb  --dry-run
```

### Output to different file

```bash
ruby ${CLAUDE_SKILL_DIR}/scripts/entity_reference.rb  -o 
```

## Example invocations

- "Fix entity references in modules/getting_started/"
- "Replace HTML entities in the assemblies folder"
- "Run entity reference transformation on all AsciiDoc files"
- "Fix the entities in modules/deploying-with-podman.adoc"
- "Preview entity changes in modules/ --dry-run"

## Behavior notes

- **Preserves supported entities**: `&`, `<`, `>`, `'`, and `"` are left unchanged
- **Skips code blocks**: Entities inside code blocks (---- or ....) are not replaced unless the block has `subs="replacements"` or `subs="normal"`
- **Skips comments**: Entities inside comment blocks (////) and single-line comments (//) are not replaced
- **Reports unknowns**: Unknown entities are reported but not modified

## Output format

```
: Replaced N entity reference(s)
  Unknown entities (not replaced):
    Line X: &unknown;
```

## Extension location

The Ruby script is located at: `${CLAUDE_SKILL_DIR}/scripts/entity_reference.rb`

## Source & license

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

- **Author:** [abhatt-rh](https://github.com/abhatt-rh)
- **Source:** [abhatt-rh/redhat-docs-agent-tools](https://github.com/abhatt-rh/redhat-docs-agent-tools)
- **License:** Apache-2.0
- **Homepage:** https://redhat-documentation.github.io/redhat-docs-agent-tools/

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-abhatt-rh-redhat-docs-agent-tools-dita-entity-reference
- Seller: https://agentstack.voostack.com/s/abhatt-rh
- 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%.