# Template design skills

> Agent-assisted template authoring with `hyperextract-skills`: brainstorm requirements, record/graph designers, yaml-validator rules, template-optimizer fixes, and multilingual conversion workflows.

- Repository: yifanfeng97/Hyper-Extract
- GitHub: https://github.com/yifanfeng97/Hyper-Extract
- Human docs: https://grok-wiki.com/public/docs/yifanfeng97-hyper-extract-7891c7254cdf
- Complete Markdown: https://grok-wiki.com/public/docs/yifanfeng97-hyper-extract-7891c7254cdf/llms-full.txt

## Source Files

- `hyperextract-skills/README.md`
- `hyperextract-skills/SKILL.md`
- `hyperextract-skills/graph-designer/SKILL.md`
- `hyperextract-skills/yaml-validator/SKILL.md`
- `hyperextract-skills/template-optimizer/SKILL.md`
- `hyperextract/templates/DESIGN_GUIDE.md`

---

---
title: "Template design skills"
description: "Agent-assisted template authoring with `hyperextract-skills`: brainstorm requirements, record/graph designers, yaml-validator rules, template-optimizer fixes, and multilingual conversion workflows."
---

The `hyperextract-skills/` directory is a portable agent skill pack that guides YAML template authoring for Hyper-Extract. It does not call LLM providers itself; skills are plain `SKILL.md` instruction files with reference rules and case YAML that any compatible local agent (Claude Code, Trae, Grok-Wiki, or another skill-capable runtime) can load from a file path or repository checkout. The root skill `hyper-extract` routes work through `brainstorm` → `record-designer` or `graph-designer` → `template-optimizer` → `yaml-validator`, with optional `multilingual` conversion. Produced templates are consumed by Hyper-Extract's runtime via `load_template()` and the `he parse --template` CLI path.

<Info>
Skill packs are provider-neutral: install by copying files into an agent's skills directory. No API keys, hosted service, or specific model vendor is required to use the design workflow.
</Info>

## Skill pack layout

```text
hyperextract-skills/
├── SKILL.md                 # Root router (name: hyper-extract)
├── brainstorm/SKILL.md
├── record-designer/
│   ├── SKILL.md
│   ├── cases/               # model, list, set examples
│   └── references/
├── graph-designer/
│   ├── SKILL.md
│   ├── cases/               # graph, hypergraph, spatio_temporal examples
│   └── references/
├── template-optimizer/
│   ├── SKILL.md
│   └── references/          # naming, multilingual, field-count, consistency
├── yaml-validator/
│   ├── SKILL.md
│   └── references/          # syntax, types, identifiers, errors
└── multilingual/SKILL.md
```

| Skill | Trigger phrases | Output |
|-------|-----------------|--------|
| `brainstorm` | "design template", "unsure which type" | Design draft with type, fields, identifiers |
| `record-designer` | model/list/set extraction | Record-type YAML |
| `graph-designer` | graph, hypergraph, temporal, spatial | Graph-type YAML |
| `template-optimizer` | "optimize template", "lint template" | Auto-fixed YAML + optimization report |
| `yaml-validator` | "validate template", "check YAML" | Pass/fail report with ERROR/WARNING/INFO |
| `multilingual` | "add translation", bilingual support | YAML with `language: [zh, en]` blocks |

## Installation

Skills install as files on disk. Copy the repository folder into the agent runtime's skills directory, or use a plugin command where supported.

<Tabs>
<Tab title="Claude Code">

```bash
cp -r hyperextract-skills ~/.claude/skills/
```

Or:

```bash
/plugin install hyperextract-skills
```

</Tab>
<Tab title="Trae">

```bash
cp -r hyperextract-skills ~/.trae/skills/
```

</Tab>
<Tab title="Other agents">

Point the agent at `hyperextract-skills/SKILL.md` as the entry skill, or copy the folder into that runtime's equivalent skills catalog. Grok-Wiki and other BYOC/BYOK agents load the same files without provider-specific adapters.

</Tab>
</Tabs>

<Note>
The canonical design reference in the main package is `hyperextract/templates/DESIGN_GUIDE.md`. Skills encode the same workflow as executable agent instructions; the design guide is the human-readable specification both skills and runtime validation align to.
</Note>

## End-to-end workflow

```mermaid
flowchart LR
  subgraph input [User input]
    U[Requirements]
  end
  subgraph skills [hyperextract-skills]
    B[brainstorm]
    RD[record-designer]
    GD[graph-designer]
    O[template-optimizer]
    V[yaml-validator]
    M[multilingual]
  end
  subgraph runtime [Hyper-Extract runtime]
    L[load_template]
    P[he parse / Template.create]
  end
  U --> B
  B -->|model/list/set| RD
  B -->|graph types| GD
  RD --> O
  GD --> O
  O --> V
  V -->|optional| M
  M --> L
  V --> L
  L --> P
```

<Steps>
<Step title="Brainstorm requirements">

Start with `brainstorm` when the extraction type is unknown. The skill asks about input source, target fields, entity granularity, relation semantics, and time/location dimensions, then emits a design draft:

```markdown
## Type: hypergraph
## Groups: [attackers, defenders]
## Fields: [battle_name, outcome]
```

Pass this draft to the appropriate designer skill.

</Step>
<Step title="Generate YAML with a designer">

Route by AutoType:

| Draft type | Skill |
|------------|-------|
| `model`, `list`, `set` | `record-designer` |
| `graph`, `hypergraph`, `temporal_graph`, `spatial_graph`, `spatio_temporal_graph` | `graph-designer` |

Each designer loads **only** the case file matching the selected type (for example `cases/earnings-summary.yaml` for `model`, `cases/corporate-ownership.yaml` for `graph`). Reference markdown under `references/` is consulted on demand, not loaded wholesale.

</Step>
<Step title="Optimize (recommended)">

Run `template-optimizer` before validation. It parses YAML, detects issues against naming, multilingual, field-count, schema-guideline separation, and hypergraph-grouping rules, then applies **Auto-fix**, **Suggest**, or **Review** changes and prints an optimization report.

</Step>
<Step title="Validate">

Run `yaml-validator` to check syntax, required fields, AutoType values, identifier configuration, and field descriptions. Validation proceeds in order: syntax → structure → identifiers → semantic warnings.

</Step>
<Step title="Add languages (optional)">

Run `multilingual` to convert single-language templates to `language: [zh, en]` with per-language `description`, `guideline`, and field description blocks. Structural keys (`name`, `type`, field `name` values, `identifiers`, `display`) stay untranslated.

</Step>
<Step title="Verify in Hyper-Extract">

Load the finished YAML through the runtime:

```python
from hyperextract.utils.template_engine.parsers.loader import load_template

cfg = load_template("path/to/template.yaml")
```

`load_template()` instantiates `TemplateCfg` and localizes each declared language; invalid configs raise `ValueError` with the failing language. Then run `he parse --template <id> --lang <lang>` or `Template.create()` as documented on the quickstart and custom-template pages.

</Step>
</Steps>

## Type selection

Both `brainstorm` and the design guide share the same decision tree:

```text
Need relationships?
├─ No → model / list / set
└─ Yes → graph / hypergraph
    ├─ Binary (A→B) → graph
    └─ Multi-entity
        ├─ Flat participants → hypergraph (simple)
        └─ Role groups → hypergraph (nested)
    ├─ + time → temporal_graph
    ├─ + space → spatial_graph
    └─ + both → spatio_temporal_graph
```

| Intent | AutoType |
|--------|----------|
| Summary card, single record | `model` |
| Ordered items, rankings | `list` |
| Deduplicated entities | `set` |
| Binary relations | `graph` |
| Multi-party events | `hypergraph` |
| Relations with timestamps | `temporal_graph` |
| Relations with locations | `spatial_graph` |
| Time + location on edges | `spatio_temporal_graph` |

## Core design principle

**Schema defines WHAT; guideline defines HOW TO DO WELL.** Every designer and optimizer skill enforces this split.

| `output` / schema | `guideline` |
|-------------------|-------------|
| Field names, types, descriptions | Extraction strategy |
| Required/optional flags | Quality requirements (naming consistency) |
| Identifier and display config | Creation conditions ("only when text explicitly states") |
| | Common mistakes to avoid |

<Warning>
Repeating field definitions inside `guideline.rules` is an optimizer **Auto-fix** target and a validator **WARNING**. Keep schema descriptions in `output`; keep behavioral guidance in `guideline`.
</Warning>

## Record designer (`model` / `list` / `set`)

`record-designer` turns brainstorm drafts into record-type YAML.

<ParamField body="output.fields" type="array" required>
Field list with `name`, `type` (`str` / `int` / `float` / `list`), `description`, optional `required` and `default`.
</ParamField>

<ParamField body="identifiers.item_id" type="string">
Required for `set` only. Names the deduplication key field (typically `name`).
</ParamField>

<ParamField body="display.label" type="string">
Template string for visualization, e.g. `{company_name}`.
</ParamField>

| Type | Identifiers | Case file |
|------|-------------|-----------|
| `model` | `{}` | `record-designer/cases/earnings-summary.yaml` |
| `list` | `{}` | `record-designer/cases/product-features.yaml` |
| `set` | `item_id: <field>` | `record-designer/cases/entity-registry.yaml` |

Field-count guidance: keep ≤ 5 fields per component; prioritize Essential → Important → Optional.

## Graph designer (graph family)

`graph-designer` produces templates with `output.entities`, `output.relations`, `identifiers`, and `display`.

### Identifier patterns

| Type | `relation_members` | Extra identifiers |
|------|---------------------|-------------------|
| `graph` | `{source: source, target: target}` | `entity_id`, `relation_id` |
| `hypergraph` (simple) | `participants` (string) | — |
| `hypergraph` (nested) | `[group_a, group_b]` (list of list fields) | — |
| `temporal_graph` | graph pattern + `time_field: time` | — |
| `spatial_graph` | graph pattern + `location_field: location` | — |
| `spatio_temporal_graph` | both `time_field` and `location_field` | — |

### Display labels

`display` drives OntoSight rendering. Edge labels must not repeat source/target node text.

| Type | `entity_label` | `relation_label` |
|------|----------------|------------------|
| `graph` | `{name} ({type})` | `{type}` |
| `hypergraph` | `{name}` | `{event_name}` or `{outcome}` |
| `spatio_temporal_graph` | `{name} ({type})` | `{type}@{location}({time})` |

Length targets: `entity_label` 5–20 characters; `relation_label` 10–30 characters.

### Hypergraph grouping

<Tip>
When relations include a `role` field but `relation_members` is a simple string (`participants`), switch to nested grouping: `relation_members: [attackers, defenders]` with matching `type: list` fields. The optimizer flags this anti-pattern automatically.
</Tip>

Common nested patterns: formula composition (sovereigns/ministers/assistants/envoys), battles (attackers/defenders), contracts (parties/witnesses).

Case files: `corporate-ownership.yaml` (`graph`), `battle-analysis.yaml` (`hypergraph`), `biography-events.yaml` (`spatio_temporal_graph`).

## Template optimizer

The optimizer runs a four-phase pipeline: parse → analyze → apply fixes → report.

| Rule file | Checks |
|-----------|--------|
| `rules-naming.md` | `relation_type` → `type`, `event_date` → `time`, snake_case fields |
| `rules-multilingual.md` | Pure `zh` / pure `en` per language block |
| `rules-field-count.md` | > 5 fields per entity/relation component |
| `rules-consistency.md` | Schema/guideline duplication |
| `rules-hypergraph-grouping.md` | Role field vs nested `relation_members` |

| Level | Behavior | Example |
|-------|----------|---------|
| **Auto-fix** | Applied automatically | Rename `relation_type` to `type` |
| **Suggest** | Proposed; may need review | Seven relation fields → simplify |
| **Review** | Design decision flagged | Open-ended vs predefined relation types |

Recommended position in the pipeline: **after designer, before validator**.

## YAML validator

Validation severity levels:

| Level | Meaning | Action |
|-------|---------|--------|
| ERROR | Blocking | Template will not load or extract correctly |
| WARNING | Quality risk | Extraction may degrade |
| INFO | Style reference | Follow for consistency |

### Required fields (all types)

- `language`: `zh`, `en`, or `[zh, en]`
- `name`: PascalCase (case YAML examples sometimes use snake_case names; validator enforces PascalCase)
- `type`: one of the eight AutoTypes
- `tags`: lowercase array
- `description`: non-empty
- `output` and `guideline`: present

### Graph-type extras

- `output.entities` and `output.relations`
- `identifiers.entity_id`, `identifiers.relation_id`, `identifiers.relation_members`
- `identifiers.time_field` / `identifiers.location_field` when applicable

### Validation order

1. Syntax (`rules-syntax.md`)
2. Structure by AutoType (`rules-types.md`)
3. Identifiers (`rules-identifiers.md`)
4. Error lookup (`rules-errors.md`)

<RequestExample>

```markdown
## Validation Results

### Syntax Validation
✅ PASSED

### Structure Validation
✅ PASSED

### Semantic Validation
⚠️ 2 warnings
- WARNING: guideline repeats field definition for `company_name`
- WARNING: relations.fields count is 7 (recommended max 5)

### Overall Assessment
✅ Configuration valid
```

</RequestExample>

Runtime validation complements the skill validator: `load_template()` re-validates localization per declared language and raises if any language block is incomplete.

## Multilingual conversion

`multilingual` converts templates between three modes:

1. **Single → bilingual** — `language: zh` becomes `language: [zh, en]` with nested `description.zh` / `description.en`
2. **Expand existing** — add missing `en` (or other) blocks to partially translated templates
3. **Add new language** — extend `[zh, en]` with `ja`, etc.

### Translatable vs fixed fields

| Translatable | Fixed (do not translate) |
|--------------|--------------------------|
| `description`, `output.description` | `name`, `type`, `tags` |
| `fields[].description` | field `name` keys |
| `guideline.target`, `guideline.rules` | `identifiers`, `display` |

Language purity rules (also enforced by optimizer):

| Language | Rule | Forbidden |
|----------|------|-----------|
| `zh` | Pure Chinese terminology | `entity(实体)` inline mixing |
| `en` | Pure English | Chinese characters in `en` blocks |

Use list format for multi-language declaration: `language: [zh, en]`.

## Naming conventions

| Element | Convention | Example |
|---------|------------|---------|
| Template `name` | PascalCase | `EarningsSummary` |
| Field names | snake_case | `company_name` |
| Relation type field | `type` | not `relation_type` |
| Time on edges | `time` | not `event_date` |
| Tags | lowercase | `finance, investor` |

## Example agent session

```text
User: I want to extract key information from financial reports

Agent (brainstorm): Clarifies fields → recommends model type

User: company name, revenue, reporting period

Agent (record-designer): Emits earnings-summary-style YAML

Agent (template-optimizer): Auto-fixes naming, flags field count

Agent (yaml-validator): Reports PASSED with 0 errors

User: Add English support

Agent (multilingual): Converts to language: [zh, en]
```

Save the final YAML under `hyperextract/templates/presets/<domain>/` or a project-local path, then register usage via `Template.create("domain/template_name")` or `he parse -t domain/template_name --lang en`.

## Failure modes

<AccordionGroup>
<Accordion title="Validator ERROR on missing identifiers">

Graph types require `identifiers.relation_members`. For `graph`, configure `source`/`target` mappings; for hypergraph, use a string (`participants`) or list (`[group_a, group_b]`).

</Accordion>
<Accordion title="load_template ValueError for language">

Every key in `language: [zh, en]` must have complete localized blocks. Run `multilingual` or manually fill missing `zh`/`en` subtrees before loading.

</Accordion>
<Accordion title="Optimizer suggests too many fields">

Split the template, move optional metadata into `description` fields, or accept **Suggest**-level warnings if domain needs exceed five fields.

</Accordion>
<Accordion title="Hypergraph role field with simple participants">

Replace flat `participants` + `role` with nested list groups. See `template-optimizer/references/rules-hypergraph-grouping.md`.

</Accordion>
<Accordion title="Agent does not pick up skills">

Confirm the skill directory path for your runtime and that the root `SKILL.md` `name: hyper-extract` is visible. Re-copy `hyperextract-skills/` after repository updates.

</Accordion>
</AccordionGroup>

## Related pages

<CardGroup>
<Card title="Create custom templates" href="/create-custom-templates">
Manual YAML authoring workflow, preset base templates, and merge strategies without agent skills.
</Card>
<Card title="Template schema reference" href="/template-schema-reference">
Field-by-field schema for `language`, `output`, `guideline`, `identifiers`, `display`, and `options`.
</Card>
<Card title="Auto-Types" href="/auto-types">
Runtime behavior of the eight AutoTypes skills target during type selection.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Runtime errors for `he parse`, missing `--lang`, and template resolution after design.
</Card>
</CardGroup>