source-command-content-definition

Use this skill when the user asks to run the migrated source command content-definition.

Command Template

CryptoGlossario — Content Definition

Encyclopedic editor for CryptoGlossario. This skill owns: definition, definitionInDepth. disciplines belongs to discipline-selector; do not patch it here. Do not touch any other field.

Fetch queue (batch mode)

Default batch size: 25. Use a different number only if the user specifies it.

getMissingDepth returns terms whose contentDefinition skill revision is below the current version — sorted by searchScore desc. Bumping the skill version in lib/skill-registry.ts automatically queues all terms, not just those missing the field.

Use bun run report:skill-plan for the global queue, or fetch terms:getMissingDepth when only this skill is requested.

For single/list mode read via the Convex MCP (data / runOneoffQuery) or use slug/id-targeted queries (terms:getBySlug, terms:getTitlesAndIds, terms:getDefinitionInDepthByIds). Never call terms:getAll and filter client-side (see CLAUDE.md, bandwidth discipline).

Canonical CryptoGlossario URLs

When a term exists in the database, its public canonical URL is:

https://www.cryptoglossario.it/definizione/[slug]

Do not require a search-engine result or web fetch to prove that URL exists. The source of truth is the local/Convex term record and its slug. If an external AI agent cannot fetch cryptoglossario.it because the URL is not visible in search results, still use the canonical URL from the record. The public machine-readable indexes are /llms.txt and /agent-glossary.json.

Batch format

``json [ { "id": "convex_id", "title": "English Term", "definition": "120-180 chars.", "definitionInDepth": "430-500 chars.", "searchScore": 50 } ] ``

Do not include disciplines here. If a discipline is wrong, handle it with discipline-selector.

``bash bun scripts/apply-content-definition-batch.ts /tmp/cg_definition_batch.json bun scripts/apply-content-definition-batch.ts /tmp/cg_definition_batch.json --apply ``

New terms

This command may draft definition and definitionInDepth for a new term, but it must not create the term by itself. New terms should enter through candidate promotion or another full-pipeline creation flow so required skills and skillRevisions stay coherent.

Editorial rules

Opening pattern: [What the thing is], [what it does / how it works]. Join the two parts with a comma or a full stop, never a colon (see the no-colon rule below).

Avoid: È un/una · Si tratta di · repeating the term as subject.

Audience: write for a curious non-specialist. The short definition must stand alone — no glossary lookup required to understand it.

No contrastive negation (applies to both fields). Do not build sentences that negate one idea only to substitute another: non X, ma Y, non è X: è Y, non si tratta di X, è Y, not X, but Y and every equivalent rhetorical reframe are forbidden as a style figure. Prefer direct, affirmative, linear statements. The only admitted exception is when the negation is technically necessary, i.e. the term's meaning genuinely depends on stating what the thing is not (e.g. distinguishing two homonyms, ruling out a common misconception that is part of the definition), and even then the pattern must be the minimum needed, not a rhetorical flourish.

No colons (applies to both fields). Do not use the colon (:) anywhere in definition or definitionInDepth. It used to be the habitual joint of the opening pattern ([cos'è]: [cosa fa]); replace it with a comma, a semicolon, or two separate sentences. The apply script rejects any colon in either field.

Structure — pick one per term:

• Map → Road: high-level concept, then concrete functioning
• Definition → Distinction: precise definition, then disambiguation

The in-depth text must not repeat the short definition.

Automatic validation. The deterministic constraints are enforced by [lib/skill-rules/content-definition.ts](../../lib/skill-rules/content-definition.ts), so the apply script flags them before anything is written: character budgets, em dash, the colon (due punti), the contrastive-negation patterns, the banned openings listed above, the tradizion- lexicon (CLAUDE.md), and glossary references in the short definition. A clean dry-run is the floor, not the goal; the rules catch regressions, they do not make the prose good. Spend your effort on the part the validator cannot check.

Reference examples. Two published entries that hit the target. Use them as style anchors, not templates to paraphrase.

Blockchain (Map → Road):

• definition: Registro pubblico e condiviso su cui vengono scritte le transazioni in blocchi collegati in sequenza, immodificabile senza il consenso della rete.
• definitionInDepth: Ogni blocco contiene le transazioni del periodo, il riferimento crittografico al blocco precedente e un dato variabile che i miner manipolano per trovare un hash valido. La struttura a catena rende impossibile modificare un blocco senza ricalcolare tutti quelli successivi, operazione che richiede il consenso della rete. Il risultato è un archivio condiviso tra migliaia di computer dove la fiducia è garantita dal codice, non da un'istituzione.

Hodl (gergo, in-depth narrativo):

• definition: Strategia di conservazione a lungo termine delle criptovalute, tenute ignorando volatilità e pressioni di vendita, senza tentare alcun market timing.
• definitionInDepth: Il termine nasce da un refuso nel post I AM HODLING pubblicato il 18 dicembre 2013 sul forum Bitcointalk durante un crollo. Scritto da un utente che si dichiara ubriaco, è diventato la battuta fondativa di una filosofia d'investimento che rifiuta il trading. Gli hodler trattengono a prescindere dai cicli, convinti che la tesi a lungo termine prevalga. La cultura crypto lo ha poi reinterpretato come acronimo di Hold On for Dear Life, consolidandone lo status di meme.

Alternative lemma forms. When title-normalization chose the lemma between two morphological variants (e.g. Token Burning vs Token Burn), name the rejected variant as a synonym so a learner sees they are equivalent ("anche detto Token Burn"). Put it in definitionInDepth; include it in the short definition only if it fits the char budget without breaking the opening pattern.

Data model: title is always the English/original lemma. Italian forms go in translation (different skill).

Cross-references to other glossary terms

The two fields follow opposite rules:

definition (short) — no glossary terms allowed, one closed exception. The short definition must be understandable by anyone, with no lookup to another entry. Do not mention any other CryptoGlossario term title unless it is in the COMMON_USE_TERMS list ([lib/common-use-terms.ts](../../lib/common-use-terms.ts)), the lemmi che la stampa generalista italiana usa senza glossa. There is no score-based exemption: a high-traffic glossary term is still off-limits in the short definition.

If a technical term is necessary but not allowed, rewrite in plain language or move the mechanism to definitionInDepth.

definitionInDepth (long) — glossary lemmas get auto-linked. Never insert markdown links.

The [LinkedText](../../components/LinkedText.tsx) component scans the rendered text and turns occurrences into internal links when the surface form matches (case-insensitive, whole-word) one of the linkable labels built by terms:getLinkableTermRefs:

• the canonical title;
• the lemma without parenthetical glosses ("NER (Named Entity Recognition)" links as NER);
• the englishPlural form ("wallets" links to Wallet).

Aliases claimed by more than one term (homonyms like Benchmark, Token) are dropped automatically: precision over recall. Italian translations, conjugations and any other surface variants are not linked, even if they correspond to a glossary entry.

Concrete rule for the editor:

• to produce a link to a glossary page, write the term as the canonical lemma (typically the English/original form, singular or plural); the parenthetical gloss is not needed;
• to refer to the same concept in Italian, accept that no link will be produced — that is the correct behavior;
• when a lemma has homonyms in different disciplines (e.g. benchmark-ai vs benchmark-computing), the bare lemma is never linked. If a link is needed, use wording that matches the full disambiguated title of the intended sense;
• COMMON_USE_TERMS that also exist as glossary titles will still be auto-linked here — that is fine; the exemption concerns only the short definition.

Clipping / accorciamenti. If the term has isClipping: true, open definitionInDepth by naming the full form in plain prose, for example "Dev è un accorciamento di Developer...". If the full form exists as a CryptoGlossario term, write its exact canonical title so the UI links it automatically. Never insert markdown links. If the full form is not in the glossary, still name the full form as normal text.