# Self Communicate

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-davisjam-model-based-agentic-software-engineering-self-communicate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [davisjam](https://agentstack.voostack.com/s/davisjam)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [davisjam](https://github.com/davisjam)
- **Source:** https://github.com/davisjam/model-based-agentic-software-engineering/tree/main/plugin/mage/skills/self-communicate
- **Website:** https://davisjam.github.io/model-based-agentic-software-engineering/

## Install

```sh
agentstack add skill-davisjam-model-based-agentic-software-engineering-self-communicate
```

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

## About

# self-communicate — write and diagram engineer-facing docs well

You are communicating **the way the work is explained** in this repository — the prose and diagrams an
engineer or a coding agent reads to understand it. This is the *communicate* leg of a trio: **govern /
operate / communicate.** [`self-governance`](../self-governance/SKILL.md) is the *harden* leg (the census
of controls and the engine that mints new ones); [`self-operations`](../self-operations/SKILL.md) is the
*operate* leg (running the substrate those controls govern). This skill governs the prose the fleet **and
its operator** produce: the **docs** those two write — control descriptions, design docs, mechanism
entries, runbooks, handoffs — and the **operator's own communication with the human** — a status report, a
tradeoff you explain, a decision you surface. The orchestrator's prose to the user is prose too. Make all
of it clear, consistent, and readable.

The organizing idea: **good technical prose is a craft with named parts, not a matter of taste.** Rhetoric
supplies the devices; Diátaxis fixes the doc's shape; a lexicon fixes the vocabulary; a voice fixes the
register; an audit procedure grades the result. Diagrams are the same craft for shapes prose can't carry.
None of this is invented per document — you reach into a toolkit and apply it.

## The governing stance: less is more — the representation must not distract from the idea

One principle governs every resource below, prose and drawing alike: **the representation is a carrier for
the idea; strip anything that does not carry it.** Three touchstones name the discipline:

- **Hemingway** — economy of words. Plain, concrete, load-bearing prose. No fluffy adjective, no ornamental
  flourish where a plain word carries the idea.
- **Tufte** — the data-ink ratio. A visual aid is the simplest form that carries its idea; strip the
  chartjunk — the gridlines, gradients, and 3-D bevels that decorate without informing.
- **Early Picasso, the bull lithographs** — the eleven-plate *Bull* reduces a bull to a few lines, each
  plate removing what the last could spare, until only the essence remains. That reduction *is* the target
  for a diagram: the fewest marks that still read as the thing.

The stance specializes per representation, and each specialization lives in its own resource rather than
being restated here:

- **In prose** — economy of words; no fluffy adjectives. Reserve flowery, ornamental language for the
  contexts that earn it (a blog post, a keynote) and use it sparingly even there. Repo prose — a reference,
  a runbook, a design doc — is plain. This extends the existing "cut qualifiers / describe don't sell"
  discipline; see [`writing/voice.md`](writing/voice.md) (§"Economy — less is more").
- **In drawing** — the simplest representation that carries the idea. Do not elaborate a diagram if a
  simpler one would read; strip ornament. See [`drawing/diagrams.md`](drawing/diagrams.md) (§"Less is more —
  the simplest form that carries the idea").

The [`writing/audit.md`](writing/audit.md) procedure flags violations of this stance in both legs — a fluffy
adjective in prose, ornament in a diagram.

## The second stance: name the concept, then use the name

A second principle governs both legs: **name the concept, then use the name — reach for the established,
native construct rather than re-deriving it from parts.** A name is a handle. It carries the concept's
meaning, its constraints, and its correct behavior in a single token, so using the name is shorter,
clearer, and less error-prone than re-describing or re-assembling the concept each time it appears. The
failure it prevents is the same in both legs: a concept re-derived from scratch on every appearance drifts,
and a construct hand-stitched from primitives is fragile in ways the native, named form is not.

The stance specializes per representation, and each specialization lives in its own resource:

- **In prose** — use the established TERM and the named design PATTERN, then link it, rather than
  re-describing the idea in fresh words each time. A recognized name — a "circuit breaker", a "state
  machine" — hands the reader the whole concept and its constraints at once. See
  [`writing/lexicon.md`](writing/lexicon.md) (§"How to use this lexicon" — "Name the established term").
- **In drawing** — use the native, named drawing construct rather than stitching one from primitives. An
  SVG `` with `orient="auto"` *is* an arrowhead: it rotates to its line and pins to the endpoint,
  so it cannot land rotated or off-target the way a hand-placed triangle `` can. Reach for the
  format's own named shape before composing one. See [`drawing/diagrams.md`](drawing/diagrams.md)
  (§"Use the native construct, not stitched primitives").

## The two legs

- **Prose** — the argument, carried in sentences. Five resources, applied in order.
- **Visualization** — the shape, carried in a diagram. One resource, Mermaid-first.

### Prose — the five resources, in order

1. **Rhetoric (the basis).** [`writing/rhetoric.md`](writing/rhetoric.md) — the device toolkit. The
   "LLM tells" (the universal em-dash, the mechanical tricolon, the reflexive "not X, but Y") are
   classical figures, not defects; the tell is *sameness and density*, the same figure on a fixed beat.
   Draw variety from the toolkit so no one figure recurs every beat.
2. **Engineering discourse / Diátaxis (the shape).** [`writing/engineering.md`](writing/engineering.md) —
   fixes the *shape* of a doc via the four Diátaxis modes (tutorial / how-to / reference / explanation).
   Decide the mode first; a how-to written as an explanation confuses the reader. The
   [`drawing/diagrams.md`](drawing/diagrams.md) leg pairs a diagram type to each mode.
3. **Lexicon (the vocabulary).** [`writing/lexicon.md`](writing/lexicon.md) — the house vocabulary of
   engineering terms-of-art, so the prose names an established idea and links it rather than re-describing
   it each time. Pick one word per concept and say it everywhere.
4. **Voice (the sensibility).** [`writing/voice.md`](writing/voice.md) — the target register with verbatim
   exemplars. Voice says what the prose should *sound* like; the engineering register says what *shape*
   it should take.
5. **Audit (the procedure).** [`writing/audit.md`](writing/audit.md) — a run-in-order procedure that grades a
   passage against all of the above and emits concrete fixes. Run it last, over the drafted prose.

### Visualization — Mermaid-first

[`drawing/diagrams.md`](drawing/diagrams.md) — the standard technical-diagram types, when to reach for each,
and how to realize one. **Default to Mermaid** (it is text, it renders in Markdown, it diffs like code);
drop to hand-authored SVG only for a geometry Mermaid can't lay out, and justify the escape. Prose carries
the argument; a diagram carries the *shape* — a structure, a flow, a lifecycle, a schema. When the thing
you are explaining has a shape, draw it.

Two peers hold the *data*-figure styles, where the content is a measurement rather than a system shape.
[`drawing/charts.md`](drawing/charts.md) — the house style for data charts (serif, three round ticks, no
title/axis labels, a restrained two-color palette, Tufte data-ink; drawn from committed data, never mocked).
[`drawing/tables.md`](drawing/tables.md) — the booktabs table style (three horizontal rules, no vertical
rules or cell borders; horizontal rules group, whitespace separates). Chart a trend, table a grid of values.

## How to use this skill

1. **Name the genre and the mode first.** What kind of doc is this — tutorial, how-to, reference,
   explanation, ADR, runbook, mechanism entry? The mode ([`writing/engineering.md`](writing/engineering.md))
   decides the shape before you write a sentence.
2. **Draft in the house voice, with varied devices.** Apply [`writing/voice.md`](writing/voice.md); reach into
   [`writing/rhetoric.md`](writing/rhetoric.md) for figures, and vary them so nothing recurs on a fixed beat.
3. **Name concepts from the lexicon.** Use [`writing/lexicon.md`](writing/lexicon.md) — one established term
   per idea, linked; don't coin a synonym for a concept that already has a name.
4. **Draw the shape where there is one.** If the content is a structure, flow, lifecycle, or schema, add a
   diagram per [`drawing/diagrams.md`](drawing/diagrams.md) — Mermaid unless the geometry forces SVG.
5. **Audit before you ship.** Run [`writing/audit.md`](writing/audit.md) over the draft and apply its fixes.

## Bootstrap the lexicon from a codebase walk — then keep it living

The lexicon ships a **portable base** (terms with an established name in the wider discipline). Your repo
also has a **house dialect** — its own coinages and the terms it reuses. You do not invent that table; you
*mine* it, then keep it current.

1. **Bootstrap by walking the codebase.** Follow the bootstrap recipe in
   [`writing/lexicon.md`](writing/lexicon.md) (§"Bootstrap recipe — walk your codebase"): sample your sources
   (the house-rules doc, a handful of design docs, your typed enums / registries / schema constants),
   extract every term you use with a specific meaning more than once, classify each as **portable** (link
   the established name) or **house** (note the standard concept it renames), and draft the table.
2. **Confirm with the maintainer.** The maintainer ratifies the preferred term and the definition — a
   lexicon nobody agreed to won't be used.
3. **Keep it living.** Re-walk periodically and whenever vocabulary drifts: a new coinage, or two words for
   one idea, is the signal to add or fix a row. **self-communicate owns the lexicon** — update it when you
   coin a term or notice drift. Keep the portable base shared; keep the house dialect local (an outside
   adopter who copies your coinages inherits terms that mean nothing in their repo).

## Notes

- **The prose the other two skills produce is this skill's work.** The controls, mechanism entries, and
  design docs written under [`self-governance`](../self-governance/SKILL.md) are prose; the runbooks,
  handoffs, and banking docs written under [`self-operations`](../self-operations/SKILL.md) are prose too.
  Write all of them in the engineering register. Going the other way: when your writing surfaces a recurring
  failure, **hand it to the [`self-governance`](../self-governance/SKILL.md) skill** to convert into a
  control; when it surfaces an operational break, **route it via the [`self-operations`](../self-operations/SKILL.md)
  skill**. The lexicon's **Governance & controls** and **Operations** clusters are the shared vocabulary all
  three skills reason in — keep those terms consistent across the trio.
- **This skill is soft.** It aims the writer at a craft; it does not itself block. The one hard control it
  suggests is running the audit procedure as a gate over prose before it ships.
- **Grade the prose, not the writer.** The audit procedure grades a passage and emits fixes. It is a
  checklist an agent runs, not a verdict on the author.

## Source & license

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

- **Author:** [davisjam](https://github.com/davisjam)
- **Source:** [davisjam/model-based-agentic-software-engineering](https://github.com/davisjam/model-based-agentic-software-engineering)
- **License:** MIT
- **Homepage:** https://davisjam.github.io/model-based-agentic-software-engineering/

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-davisjam-model-based-agentic-software-engineering-self-communicate
- Seller: https://agentstack.voostack.com/s/davisjam
- 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%.