Guide Writing

Documents

guide-writing

Guide Writing is an Agent Skill for documents published in the ubolonton/emacs-module-rs repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when writing or editing guide docs — files under guide/src/

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/ubolonton/emacs-module-rs/blob/HEAD/.claude/skills/guide-writing/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/guide-writing, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Guide Writing

Overview

This skill captures the writing style of the guide/ mdbook. Apply it when creating or modifying any file under guide/src/.

Voice & Tone

Active voice throughout; imperative for setup steps ("Create a file", "Modify Cargo.toml")
No hedging: "must" not "should ideally", "returns" not "will typically return"
Semi-formal: engineer-to-engineer, no marketing fluff, no filler transitions

Sentence & Section Length

Sentences: 10–25 words; split complex ideas rather than stacking clauses
Sections: 10–40 lines; one focused idea per section

Teaching Approach

Code first, explanation after. Show a working example, then extract the key point.

// Show this first, then explain what's happening
#[defun]
fn inc(x: i64) -> Result<i64> {
    Ok(x + 1)
}

Progressive complexity: simple case first, advanced options after
Explain trade-offs explicitly when presenting multiple options — don't just list them
Call out failure modes and edge cases directly; don't gloss over them

Structure

Content type	Format
Reasoning / rationale	Prose
Options / parameters	Bullet list (one line each; prose for elaboration)
Setup sequences	Numbered steps or sequential bash blocks
Complete patterns	Fenced code block
Identifiers in prose	Backtick inline code

Audience Assumptions

Readers know Rust or Emacs well — no hand-holding for either domain's fundamentals
C FFI concepts (raw pointers, extern, cdylib) are understood
Don't explain what &mut, Box, or Result mean

Code Examples

Substantial enough to copy-paste and run
Include both Rust and Elisp when showing a Lisp-facing API
Use real scenarios (e.g. wrapping a hash map, a git repo) not toy abstractions
One good example beats several mediocre ones

Terminology

Precise and consistent: pick one term and use it throughout (e.g. always "type conversion", never "type casting")
Domain terms — defun, user-ptr, GIL, signal, throw — used without apology or inline definition

Common Mistakes

Passive voice: "The type can be embedded" → "You can embed the type"
Over-hedging: "Note that you may want to consider using..." → "Use X when Y"
Listing options without trade-offs: always say when to prefer each
Leaking project internals: CI matrices, supported OS counts, test version lists — omit unless directly relevant to the reader's setup