| name | introducing-terms |
| description | Use when adding or defining a Virto Commerce vocabulary term, mapping a Virto Commerce concept to its industry name, or processing a batch of such terms. Triggers include "add term", "define term", "introduce term", "map to Shopify/Magento/commercetools name". |
Introducing terms
Workflow for adding terms to the Virto Commerce glossaries and, where warranted, to the abbreviation tooltips. One term or a batch.
Authoritative rules live in CLAUDE.md §Glossaries, §Abbreviation tooltips, §Verification before claims. This skill is the applying procedure; do not restate rules here.
Iteration
Per-term full-pass. No batching of verification or drafting across terms: evidence decouples from claims.
Inputs per term
- Term as the Virto code names it.
- Audience: business, developer, or both.
- Suspected industry analog (unverified).
Workflow
1. Verify Virto vocabulary
Per CLAUDE.md §Verification before claims.
- Symbol existence: GitHub MCP search plus file fetch in the
VirtoCommerce org. Org/repo filter plus quoted string is required; unfiltered queries return empty. Fetch the hit to confirm location.
- Prose form: grep the docs corpus for frequency. Highest count wins; record the count.
2. Verify cross-platform terminology
Per CLAUDE.md §Cross-platform comparison table and §Verification before claims.
- One primary-source fetch per cell (vendor's own docs).
- WebFetch returning 403 → fall back to WebSearch with
allowed_domains on the vendor's primary docs host.
- Cell unverifiable →
n/a. Most cells unverifiable → drop the table.
3. Decide ownership and draft the entry
Decide which glossary owns the term per CLAUDE.md §Glossaries → Ownership routing. Create the owning glossary file if absent.
Gate: no draft text until steps 1–2 have produced verified names from tool output. Before drafting, sample 2–3 adjacent entries at the insertion point; match sentence length, voice, density. Apply CLAUDE.md §Entry shape and §Cross-platform comparison table to the draft.
4. Add an abbreviation tooltip if applicable
Per CLAUDE.md §Abbreviation tooltips: eligibility, scope (base vs overlay), casing/plural variants.
5. Cross-link from every guide
Survey procedure for CLAUDE.md §Linking from other pages.
- Per guide, recursive grep the term; group hits by first path segment under
docs/ to enumerate top-level sections (or standalone pages).
- For each section, link first occurrence on its entry page to the owning glossary. Form per CLAUDE.md.
- No relink in deeper pages of the same section; no self-link on the canonical glossary page.
- Skip auto-rendered API references (e.g.,
GraphQL-Storefront-API-Reference-xAPI/) unless an authored overview exists; link from the authored overview only.
6. Per-term self-check
Evidence trail for CLAUDE.md rules:
- Fundamentals identified from code before drafting (§Entry shape).
- Every class/interface/namespace/vendor cell traces to a tool call this session (§Verification before claims).
- Entry shape, comparison table, bidirectional cross-link applied (§Glossaries).
- Tooltip eligibility decided (§Abbreviation tooltips).
- Owning glossary identified, link form correct (§Linking from other pages).
- All seven content guides surveyed.
- Scope locked; no drive-by edits.
Common mistakes
| Mistake | Fix |
|---|
| Internal, schema-level, or developer-only vendor name instead of merchant-facing label. | Use the label from that vendor's admin-facing docs. |
| Developer jargon (runtime, schema, interface) in a user-facing entry. | Rewrite for a non-developer reader. |
| Enumerating every related interface in a developer-facing entry. | Move detail to the deep-dive page. |
| Backticking proper nouns like "Shopify" or "commercetools". | Plain text. |
| Drafting before identifying the concept's fundamental properties (user-defined? runtime? EAV?). | List shared properties with the sibling entry first; opener mirrors shared nature. |
| PascalCase identifier or implementation-pattern label in a dev-guide table cell. | Use general prose form, or n/a (uses X) if the platform collapses the distinction architecturally. |
| Adding a multi-word vocabulary term to abbreviations.yml because it has a short definition. | Glossary entry plus cross-link instead. |
| Linking the glossary on every page that mentions the term. | One link per top-level section, on its entry page. |
| Restating rules in this skill instead of pointing to CLAUDE.md. | Keep this file workflow-only; cite the rule section by name. |
