@human-avatar/skills-for-humanity 1.0.0

package/skills/writing-technical/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: writing-technical
+description: "Writes and audits technical documentation, API docs, user guides, and specifications for completeness, sequence, precision, and audience calibration. Use when documentation is confusing, assumes too much knowledge, or leaves gaps a user can't bridge. Triggers: 'technical writing', 'API documentation', 'write documentation', 'user guide', 'technical docs', 'the documentation is confusing', 'write a spec', 'docs are missing steps'."
+---
+
+# Writing: Technical
+
+Technical writing fails when it is written for the person who already knows how the system works. The person who already knows doesn't need the document. The document is for the person who doesn't know — and that person's experience of the document is the only test that matters. The test is simple: can a reader with the assumed knowledge execute the task using only this document? If they cannot, something is missing.
+
+This is a higher bar than it sounds. Technical writers who know the system well have difficulty seeing the gaps — because for them, nothing is missing. The prerequisite knowledge is so obvious it doesn't seem worth stating. The step that requires understanding the system's mental model doesn't look like a step — it looks like common sense. These invisible assumptions are where most documentation fails.
+
+The five failure modes in technical writing:
+
+**Audience miscalibration:** Assumes knowledge the reader doesn't have, or over-explains what the reader already knows. Both are wrong. The first makes the document unusable; the second makes it condescending.
+
+**Incompleteness:** Steps that require bridging knowledge the document doesn't provide. Often invisible to the writer because the knowledge is automatic.
+
+**Sequence errors:** Prerequisites stated after they are needed, steps in the wrong order, troubleshooting information buried after the task it applies to.
+
+**Precision failures:** Terms used inconsistently, ambiguous instructions ("configure the settings" — which settings?), passive voice that obscures who does what ("the file should be saved" — by whom, when, where?).
+
+**Missing examples:** Non-obvious steps explained only in the abstract, without a concrete example that shows the reader what the correct output looks like.
+
+---
+
+## Your Process
+
+**Step 1: Audience Profile**
+Who is the reader? What do they already know? What do they not know? What is their goal — and what is the fastest path from their current knowledge to task completion? Is the documentation calibrated to this profile, or to a different one (a more advanced user, or a more novice one)?
+
+**Step 2: Completeness Audit**
+Read the documentation as if you are the assumed reader and have only their assumed knowledge. Walk through each task:
+- Are all prerequisites stated before they are needed?
+- Is there any step that requires knowledge not provided in this document or in the stated prerequisites?
+- Are error states covered? (What does the reader do if the expected result doesn't happen?)
+- Are edge cases relevant to the assumed reader addressed?
+
+Flag every gap: name the missing knowledge, identify where in the sequence the reader would encounter it.
+
+**Step 3: Sequence Audit**
+Check the order of information:
+- Are prerequisites stated before the tasks that require them?
+- Are steps in chronological order?
+- Is troubleshooting information positioned near the steps it applies to, not collected at the end?
+- Is the most important information (the task itself) reached without having to navigate through extensive context?
+
+**Step 4: Precision Audit**
+For every instruction, ask: could a reader with assumed knowledge interpret this in two different ways?
+- Flag ambiguous instructions (specify what, where, when, and who)
+- Check that technical terms are used consistently throughout (not "configuration file" in one place and "config" in another without establishing the shorthand)
+- Check that passive voice doesn't obscure agency ("the token should be set" → "set the token in the environment variable `AUTH_TOKEN`")
+
+**Step 5: Examples Audit**
+Identify non-obvious steps — steps where the correct action or its output is not self-evident to the assumed reader. For each:
+- Is there an example showing correct usage?
+- Is there an example showing what the correct output looks like?
+- For API documentation: are there example requests and responses?
+
+---
+
+## Output Format
+
+### Technical Writing Audit
+
+**Audience Calibration:** [Who the assumed reader is / Whether the documentation matches that reader / Specific miscalibrations]
+
+**Completeness Gaps:**
+- [Missing knowledge / Where the reader encounters the gap / What would fill it]
+- NONE FOUND if complete
+
+**Sequence Issues:**
+- [What comes in wrong order + correct placement]
+- NONE FOUND if correct
+
+**Precision Flags:**
+- [Quoted ambiguous instruction → Precise rewrite]
+- [Inconsistent term usage identified]
+- NONE FOUND if precise
+
+**Missing Examples:**
+- [Step that needs an example + suggested example type]
+- NONE FOUND if all covered
+
+**Rewrite Suggestions:** [Worst-offending sections rewritten with all issues addressed]
+
+---
+
+## Notes
+
+- The completeness test is the only test that matters: can the assumed reader complete the task using only this document? Walk through the steps as that reader, not as the author.
+- The most commonly missed completeness gap: the mental model. Some tasks require the reader to understand *why* a system works a certain way before the steps make sense. If that mental model isn't provided, the steps are technically present but functionally useless.
+- Pairs with `/writing-audience-calibration` — audience profile is the anchor for every other decision; the calibration audit belongs here.
+- Pairs with `/writing-restructure` — documentation structure often needs reordering, particularly moving prerequisites before the steps that need them.
+- Pairs with `/writing-line-editing` — technical writing often suffers from passive voice and nominalisation; line editing is often the final pass.

package/skills/writing-tone-alignment/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: writing-tone-alignment
+description: "Diagnoses and repairs tone drift — shifts in register, formality, warmth, or rhythm that make a piece feel like it was written by multiple people or in multiple moods. Use when the voice changes mid-piece without intention. Triggers: 'the tone keeps shifting', 'tone drift', 'tone alignment', 'inconsistent register', 'the voice changes mid-piece', 'this sounds like different writers'."
+---
+
+# Writing: Tone Alignment
+
+Tone drift is what happens when a piece moves through multiple registers without intention — formal to casual, warm to clinical, urgent to contemplative — destroying the reader's sense of who is speaking. The reader cannot trust a voice they cannot locate. When they feel the voice shift, they become aware they are reading a *document* rather than inhabiting a communication. The intimacy, or the authority, or the momentum — whatever the piece was building — dissolves.
+
+Tone drift is most common in three situations: multi-author documents, where different contributors have different natural voices; long pieces written over time, where the writer's mood, energy, or approach has changed between sessions; and pieces assembled from different source material, where the register of the sources bleeds into the synthesis.
+
+Tone has multiple dimensions, and they can drift independently:
+- **Formality:** Where on the formal/informal spectrum? Legal prose to text message — everything between is possible, but the piece should occupy a consistent bandwidth.
+- **Warmth:** Where on the cold-to-warm spectrum? Institutional distance to personal intimacy?
+- **Urgency:** Is the piece pressing forward, or is it contemplative and spacious?
+- **Stance toward the reader:** Does it treat the reader as a peer, a student, a customer, a collaborator, a stranger?
+- **Sentence rhythm:** Short and punchy, or long and periodic? The rhythm carries register even when the words don't shift.
+
+---
+
+## Your Process
+
+**Step 1: Intended Tone**
+What tone was intended? If it's not stated, extract it from the strongest passage in the piece — the section that works best is the baseline. State the intended tone precisely across all five dimensions: formality level / warmth level / urgency / stance toward reader / sentence rhythm.
+
+**Step 2: Scan for Departures**
+Read through the piece and flag sections where any of the five tone dimensions shifts from the baseline. Don't just flag "informal" or "formal" — be specific: "this section shifts from 'collegial peer' to 'authoritative expert'"; "this paragraph breaks from short declarative sentences into subordinate clause-heavy long sentences that slow the pace and change the register."
+
+**Step 3: Diagnose the Cause**
+For each departure, what produced it?
+- **Source bleed:** The tone of a cited source or reference has leaked into the prose
+- **Multi-author drift:** A different contributor's natural voice
+- **Energy change:** Written in a different session, different mood, different urgency
+- **Register confusion:** The writer shifted their mental audience for this section
+- **Functional shift:** The section is doing something different (explaining vs. persuading vs. narrating) and the register shifted with the function without awareness
+
+Understanding the cause determines the correction.
+
+**Step 4: Prescribe Corrections**
+For each flagged section: what specific changes bring it into alignment? This may involve vocabulary choices ("synergistic" → "works well together"), sentence length adjustments, the removal of hedging language, or the addition of warmth. Be specific — "make it more casual" is not actionable; "replace the three nominalisations in this paragraph and cut the passive construction in the final sentence" is.
+
+---
+
+## Output Format
+
+### Tone Audit
+
+**Intended Tone:**
+- Formality: [X/10, characterised]
+- Warmth: [X/10, characterised]
+- Urgency: [paced characterisation]
+- Stance toward reader: [peer / student / customer / etc.]
+- Sentence rhythm: [characterised]
+
+**Flagged Departures:**
+- [Location] — [Quoted passage] — Dimension shifted: [formality / warmth / urgency / stance / rhythm] — Direction of drift: [toward formal / toward casual / etc.]
+- [Repeat for each]
+- NONE FOUND if clean
+
+**Cause Diagnoses:** [Per departure: source bleed / multi-author drift / energy change / register confusion / functional shift]
+
+**Correction Prescriptions:** [Per departure: specific changes — vocabulary, sentence structure, register adjustments]
+
+---
+
+## Notes
+
+- Tone drift is different from intentional register shift. Some pieces move between registers deliberately — a piece that shifts from formal analysis to personal reflection is doing something intentional. The question is whether the shift is marked and controlled, or whether it just happens.
+- Tone drift is most damaging at openings: if the first two paragraphs are not tonally consistent with each other, the reader never establishes their footing.
+- Pairs with `/writing-voice-consistency` — voice is the who speaking; tone is the how. They are related but distinct. Voice consistency asks "does this sound like the same person?"; tone alignment asks "is that person speaking in a consistent register?"
+- Pairs with `/writing-audience-calibration` — tone is part of calibration; a piece can be tonally consistent but calibrated to the wrong audience entirely.
+- Pairs with `/writing-line-editing` — many tone corrections happen at the sentence level (word choice, sentence structure), so the two tools often work together.

package/skills/writing-voice-consistency/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: writing-voice-consistency
+description: "Extracts a voice fingerprint from strong existing passages and uses it to audit and repair voice departures. Use when multiple contributors have created a fractured document, when brand voice has drifted, or when the writing doesn't sound like one person. Triggers: 'the voice isn't consistent', 'voice consistency', 'this doesn't sound like us', 'multi-author document', 'maintain voice', 'brand voice', 'the writing sounds like different people'."
+---
+
+# Writing: Voice Consistency
+
+Voice is the sum of choices: sentence length preference, vocabulary range, degree of formality, stance toward the reader, use of metaphor and analogy, tolerance for digression, the character that comes through even in functional writing. It is recognisable even when you can't name what you're recognising. When it's absent or fractured, the reader feels it as a nagging sense that the writing has no centre — that no one is actually speaking to them.
+
+The critical insight: voice can be *extracted* and *characterised* from strong existing passages, and that characterisation becomes an auditable standard. This means voice consistency is not a mysterious quality that can only be felt — it is a set of identifiable, describable choices that can be held constant across contributors, sections, and time.
+
+For brand and organisational writing, this extracted voice fingerprint becomes the foundation of a practical style brief — not a list of rules about comma usage, but a description of who is speaking and how they sound, with examples that any contributor can use as a reference.
+
+---
+
+## Your Process
+
+**Step 1: Extract Defining Characteristics**
+From the strongest existing passages — the sections that feel most alive, most like the brand or the writer's best work — identify 5–7 defining characteristics. These should be specific enough to be testable. Not "clear and friendly" but:
+- Sentence length: typically 12–20 words; occasional short declaratives for emphasis (under 8 words)
+- Vocabulary: specific and concrete; avoids jargon; uses domain terms but never without context
+- Formality: conversational but not casual; writes to a peer, not down to a student
+- Stance: confident, never hedging; does not over-qualify claims
+- Metaphor: uses one extended metaphor per piece; ground-level comparisons not elevated ones
+- Rhythm: often ends sections with a short sentence that lands a point
+- Attitude to reader: assumes reader is intelligent and pressed for time; doesn't repeat
+
+**Step 2: Create a Voice Fingerprint**
+Write a representative passage (or select the strongest existing one) that exemplifies all 5–7 characteristics simultaneously. This is the voice fingerprint — the reference point that any subsequent section can be held against. It should feel unmistakably like the voice.
+
+**Step 3: Scan for Departures**
+Read through the full document and flag sections that depart from the fingerprint. For each departure:
+- Quote the passage
+- Identify which characteristic(s) it violates
+- Describe the direction of departure (toward formal / toward casual / toward hedging / toward corporate / etc.)
+
+**Step 4: Build a Voice Guide (for brand/multi-author use)**
+For documents that will have multiple contributors or ongoing updates, translate the fingerprint into a brief, practical guide:
+- The voice in one paragraph (descriptive, not prescriptive)
+- 5–7 DO / DON'T pairs with examples
+- The representative fingerprint passage as the reference sample
+- The 3 most common departures to watch for, with before/after examples
+
+---
+
+## Output Format
+
+### Voice Analysis
+
+**Fingerprint (5–7 Characteristics):**
+1. [Characteristic: specific and testable]
+2. [And so on]
+
+**Representative Sample Passage:** [The passage that exemplifies all characteristics — quoted from existing text or composed if no strong existing passage exists]
+
+**Departures:**
+- [Location] — [Quoted passage] — Characteristic(s) violated: [list] — Direction of departure: [description]
+- [Repeat]
+- NONE FOUND if clean
+
+**Voice Guide (for brand/multi-author use):**
+- [Voice in one paragraph]
+- [DO/DON'T pairs with examples]
+- [Most common departures to watch for]
+
+---
+
+## Notes
+
+- The voice fingerprint works only if it is extracted from the best existing work, not invented. A voice brief built from aspirational writing that doesn't match the actual document will not solve the consistency problem — it will create a new one.
+- For single-author documents, voice departures are usually caused by energy, time, or tone shifts. For multi-author documents, they're usually caused by each contributor's natural voice overriding the house voice.
+- Pairs with `/writing-tone-alignment` — tone is one dimension of voice. Voice consistency addresses the full identity of the speaker; tone alignment addresses one specific dimension (register).
+- Pairs with `/writing-audience-calibration` — voice must be calibrated to the audience; a perfectly consistent voice that is calibrated to the wrong reader is still failing.
+- Pairs with `/writing-prose-elevation` — elevation must stay in voice; an elevated passage that sounds like a different writer has traded one problem for another.

package/skills/writing-worldbuilding/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: writing-worldbuilding
+description: "Audits a fictional world for internal consistency, texture, economy, and constraint-story alignment. Use when a world feels thin, generic, like a backdrop rather than a place people actually inhabit. Triggers: 'the world feels thin', 'worldbuilding', 'my world doesn't feel real', 'the setting is generic', 'world audit', 'the world feels like a backdrop'."
+---
+
+# Writing: Worldbuilding
+
+Worlds fail when they are described rather than inhabited. The difference is texture. A described world tells you what things are — "a dystopian future where technology controls society." An inhabited world shows you what it costs to live there: what people eat, what they fear, what they fight over, what they take for granted, what they lie about. The first is a category. The second is a place.
+
+The test of a well-built world is not comprehensiveness — it's necessity. Does the world create the story's conflict, or is it merely a backdrop? In a well-integrated world, the story's central problem could only happen in this world, in this configuration. The colony's resource scarcity creates the political structure that creates the protagonist's impossible choice. Remove the world, and the story doesn't exist. In a backdrop world, you could set the same story in contemporary New York without changing anything essential.
+
+The second test: specificity of texture. The world must feel inhabited not through encyclopaedic exposition, but through specific, surprising detail that implies a larger reality. One specific food item, one specific ritual, one specific slang term tells the reader more about the world than three pages of history. The detail does double duty — it characterises the world and implies the systems that produced it.
+
+---
+
+## Your Process
+
+**Step 1: Rules**
+Map the world's governing systems: physical, social, technological, magical, or political. What are the rules that cannot be broken? Are they internally consistent — does the magic system create loopholes the story conveniently exploits? Does the technology appear and disappear based on plot convenience? Rules only function as worldbuilding if they constrain the story.
+
+**Step 2: History**
+What happened before the story? How does it shape present conditions? The world's history should be visible in the present: in architecture, language, prejudice, ritual, scar tissue. If the history is not visible in the present, it has no function — it's backstory for the author, not texture for the world.
+
+**Step 3: Economy**
+How do people survive? How is power acquired and maintained? What do people trade, compete for, hoard, or sacrifice? Economy is the hidden architecture of any world — it determines who has leverage over whom, what choices are available to which people, and what the stakes of any conflict actually are. Worlds without a legible economy feel arbitrary.
+
+**Step 4: Texture**
+Specific details that make the world inhabited — not the large-scale facts, but the granular particulars: food, clothing, speech patterns, rituals, insults, jokes, signs, smells. For each world zone (a location, a social class, a faction), identify what specific sensory details are present and what is missing. The test: could these details only exist in this world, or are they generic?
+
+**Step 5: Constraint-Story Alignment**
+Does the world's structure create the story's conflict, or is the world irrelevant to the plot? This is the integration test. Map the connection: world rule → social consequence → character situation → story problem. If the chain breaks at any point, the world is decorative rather than load-bearing.
+
+---
+
+## Output Format
+
+### World Audit
+
+**Rules Inventory:** [Physical / social / technological / magical governing rules — internal consistency check — loopholes or conveniences flagged]
+
+**History:** [Pre-story events + how they're visible in the present / missing historical presence flagged]
+
+**Economy:** [Survival mechanisms / power acquisition / what is competed over / leverage structures / gaps or arbitrary elements]
+
+**Texture:** [Present specific details — per zone if relevant / Missing sensory/cultural particulars / World-specific vs. generic details distinguished]
+
+**Constraint-Story Alignment:** [The chain: world rule → social consequence → character situation → story problem / Where the chain breaks]
+
+**Gaps and Inconsistencies:** [Internal contradictions / rules violated by plot convenience / areas requiring further development]
+
+---
+
+## Notes
+
+- The most common worldbuilding error is exposition: delivering world information through characters explaining things to each other. World texture should emerge through action, conflict, and specific detail — not through characters lecturing.
+- Comprehensiveness is not the goal. A world that feels real is not one where every question has been answered — it's one where the questions the story raises are answered, and the answers feel like part of a larger coherent system.
+- Pairs with `/writing-inconsistency-audit` for world-rule violations throughout the manuscript — worldbuilding establishes the rules; the audit finds where they're broken.
+- Pairs with `/writing-character-development` because characters are produced by their world: their wound, defence, and want are shaped by the economy, history, and social rules they grew up inside.
+- Pairs with `/writing-scene-construction` for deploying world texture at the scene level — what sensory details make this specific location feel inhabited.