# Semantic Draft Writer

> >

- **Type:** Skill
- **Install:** `agentstack add skill-siddiqss-semantic-seo-suite-semantic-draft-writer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [siddiqss](https://agentstack.voostack.com/s/siddiqss)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [siddiqss](https://github.com/siddiqss)
- **Source:** https://github.com/siddiqss/semantic-seo-suite/tree/main/skills/semantic-draft-writer

## Install

```sh
agentstack add skill-siddiqss-semantic-seo-suite-semantic-draft-writer
```

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

## About

# semantic-draft-writer

Turn a brief into publishable copy that is deep, specific, extractive, and — the part
other tools skip — factually honest. "Passes the validator" is the floor, not the goal:
the goal is a piece genuinely worth reading. The draft is done when it is fabrication-clean
AND clears the quality bar (or its remaining gaps are explicitly surfaced).

Read first: `../../framework/semantic-writing-rules.md` (especially the **Craft & depth
rules 22–28**), `../../framework/macro-micro-semantics.md`. Load the brief, the node,
`brands//locked-facts.json`, and `entity-profile.json` (for voice/audience).

## Workflow

0. **Scope depth and surface fact gaps FIRST.** Before writing, list the concrete
   specifics a strong piece needs — real examples, named entities, figures, a point of
   view — and check them against `locked-facts.json` + the brief. If the piece can only be
   written generically because the facts aren't there, that is a signal to **ask the user
   for the missing specifics** (real customer result, actual feature names, a workflow
   detail) rather than writing vague filler. Thin facts are the #1 cause of thin drafts.

1. **Front-matter first.** Emit the required block (semantic-writing-rules.md): node_id,
   target_query, intent, entities_covered, internal_links, schema_type,
   locked_facts_used (start empty), sources (start empty).

2. **Draft for a reader, section by section along the brief's contextual vector.** Lead a
   section with the extractive answer (rules 3–4) THEN go deep: mechanism, a concrete
   example (rule 23), a trade-off, a real point of view (rule 26). Do not turn every H2
   into a tiny Q&A (rule 27) — vary the shape. Declarative, specific, filler-free.

3. **Honour the locks while writing:**
   - State a brand fact ONLY if it exists in `locked-facts.json`; when you use one, add
     its key to `locked_facts_used`.
   - State an external factual number ONLY with a citation; add the URL to `sources`.
   - Where a figure would help but isn't grounded, write the honest version (mechanism/
     range/"depends on…") — never invent one. Pull from the brief's `do_not_fabricate`.

4. **Insert internal links** from the brief with varied, descriptive anchors
   (internal-linking-rules.md).

5. **Editorial self-critique pass (before the gates).** Re-read the draft as a skeptical
   editor: Which section is thin? Where is there no example? What's the non-obvious point,
   and is it actually there? Cut every filler sentence. Rewrite the weakest section. Do
   this once *before* running the scorers — the gates confirm quality, they don't create it.

6. **Three-gate loop — fabrication is a hard gate; quality is the target; AEO is a floor:**
   ```
   # (a) HARD GATE — must be 0 high, or surface remaining violations
   python ../../scripts/validate_draft.py --draft  \
     --locked brands//locked-facts.json --brief brands//briefs/.json \
     --brand-terms "" --json
   # (b) QUALITY — the number to optimize (target >= 80)
   python ../../scripts/draft_quality.py --draft  --floor  --json
   # (c) AEO — a FLOOR to clear (target >= 80), NOT a number to maximize
   python ../../scripts/aeo_score.py --draft  --schema-dir brands//data/schema --json
   ```
   Repair in priority order: fabrication first (never fix a fabrication by inventing a
   source — tell the truth or cut the claim); then work the `draft_quality.py` fixes
   (deepen shallow sections, add the missing examples, cut filler, reach length through
   depth); then confirm AEO ≥ ~80. **Do not sacrifice depth to push AEO past ~85** — a
   formulaic all-Q&A page is the failure mode this loop exists to prevent. Repeat ~2–4×.

7. **Surface, don't hide.** If violations or an unavoidable quality gap remain (e.g. the
   piece stays generic because a brand fact the user hasn't confirmed is missing), STOP
   and list them with the exact sentences and the specific facts you need — rather than
   shipping filler or faking a source. These usually map to `_pending_owner_confirmation`.

8. **Emit** `brands//drafts/.md`; set node `status: drafted`.

## Definition of done
- `validate_draft.py`: 0 high-severity violations (or remaining ones surfaced with rationale).
- `draft_quality.py`: **>= 80** — every section has depth and a concrete example; filler
  is gone; length reached through substance. This is the bar the writer is judged on.
- `aeo_score.py`: **>= 80** (floor cleared; not maximized at the cost of depth).
- Front-matter accurate; reads as a genuine expert with a point of view, not a padded FAQ.

## Grounding ladder
- **T0:** research external facts via web_search (cite them); brand facts from locked
  ledger only.
- **T1+:** same rules; richer sourcing. Grounding tier never relaxes the fabrication
  guard — it only changes where legitimate numbers come from.

## Source & license

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

- **Author:** [siddiqss](https://github.com/siddiqss)
- **Source:** [siddiqss/semantic-seo-suite](https://github.com/siddiqss/semantic-seo-suite)
- **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-siddiqss-semantic-seo-suite-semantic-draft-writer
- Seller: https://agentstack.voostack.com/s/siddiqss
- 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%.