Skills guide

For a guided path, copyable invocation examples and the full on-site reference, use the documentation website. This skills guide is also rendered there directly from this file on each build.

Voice Forge has sixteen skills: one main skill that holds all the rules, and fifteen shortcuts that start it in a specific mode.

The / form works in Claude Code and Kilo. In Codex, type $ instead of /. In other agents, name the skill in plain words.

Profiles

A profile is one voice for one context. Each profile has a brief at the top that says what it is for, who reads it, the field and its venues. For example:

Every nonfiction profile has the same ten sections: (1) identity and context, which is the brief; (2) document architecture; (3) argument; (4) paragraphs; (5) discourse and coherence; (6) sentences and rhythm; (7) vocabulary; (8) voice and metadiscourse; (9) evidence and sources; (10) anti-patterns. Each of sections 2 to 10 is established (it has your approved rules), unknown (not enough evidence yet, the normal start) or not_applicable (it does not fit this kind of writing, with a reason). Each rule says what to do, where it applies, its exceptions, how strict it is (mandatory, preferred, optional or prohibited) and how a reviewer checks it. The details are in schema-nonfiction.md. vf.py validate checks every profile against it.

Profiles are independent. The agent uses one profile at a time, plus a few rules in base.md that are true in all your writing. It never mixes two profiles, so a bold voice for one context does not leak into a careful voice for another.

How the agent picks the profile:

1. The one you name.
2. Otherwise, the one whose brief clearly matches the task.
3. Otherwise, default-en or default-es, by language.

voice-forge: the main skill

What it is for: everything. It holds the rules for meaning, slop and your voice, plus the instructions for each mode.

When it starts: you don't need to call it. The agent loads it on its own when you ask for text "in my voice", «que suene como yo», or name a profile. The shortcuts below start it too.

What it always does, in every mode:

• Finds your voice home (the folder setup recorded, ~/.voice-forge by default) and picks the profile as described above.
• Keeps the voice home in sync: gets the latest version at the start of a session, and saves and pushes to your private repo after every change.
• Offers to log a problem in your feedback file when you complain about how it behaved.
• Never changes facts, numbers, names, quotes, uncertainty or code.
• Never adds a rule to your profile without your yes on the exact words.
• Checks the final text for AI phrases, dashes and Spanish quote marks before giving it to you.

/vf-train: practice rounds

What it is for: teaching the agent how you write. This is the main way a profile grows.

How: /vf-train economics-en. Optional extras: a topic (/vf-train economics-en survey-weights) or a focus (openings, closings, transitions, data, hard).

Own-text rounds: /vf-train economics-en from paper.pdf. Instead of writing a passage, the agent takes a paragraph from your own text and you rewrite it as you would write it today. This is the best way to separate your voice from your coauthors' and from habits you have outgrown.

What happens:

1. The agent writes 1 or 2 plain paragraphs on a topic from your list.
2. You rewrite them your way. You can also answer OK (you would keep it), skip (new topic) or stop.
3. It saves the round as a file.
4. It shows what you changed, separating content changes (a fact you fixed) from voice changes (how you say things).
5. It proposes up to 3 lessons. You answer yes, no, or a better wording.
6. Every 5 rounds, it shows the lessons with enough evidence and asks if they should become rules. Enough means 3 rounds on 2 topics, or 2 rounds plus support from an analysis. For each, it shows the whole rule: the instruction, where it applies, the exceptions, how strict it is and how it will be checked. You approve the whole block.

What it changes: a new round file, lessons.md, and rules.md only when you approve a promotion. Then it saves and pushes.

/vf-draft: write something new

What it is for: new text in your voice, such as an email, a memo or a section of a chapter.

How: /vf-draft default-en a 200 word email to my team about the new survey round.

What happens:

1. It reads the profile's brief, its rules, and 2 or 3 examples of your own writing from that profile, and keeps only the rules that apply to this task.
2. It plans by section: the order of ideas, the main claim and its support, one line per paragraph, where each number goes.
3. It writes the text. It uses only facts you or a source gave it, and leaves a [TODO] marker where something is missing.
4. It runs the mechanical checks (lint.py, measure.py check), then has a reviewer check every rule. In agents that can start a separate agent, the reviewer is independent; otherwise it says it is not.
5. It fixes what failed, changing only those spots, and stops after at most two reviews. It gives you the text, plus one line for anything it could not fix.

What it changes: nothing in your profile. If it writes the draft into a file in a git repo, it commits only that file, labeled vf-draft, so /vf-learn can later compare it with your edits.

/vf-edit: fix existing text

What it is for: making a text sound like you with the smallest change. The text can be yours or AI-written.

How: /vf-edit report.md, or /vf-edit explainer-es followed by pasted text.

What happens:

1. It marks AI phrases, places that break your rules or the conventions in the brief, and real errors.
2. It changes only those spots. If the text is already good, it says so and leaves it alone. It does not reorder sections or rebuild paragraphs unless you ask; it reports those problems instead.
3. It never deletes a claim to satisfy a rule.
4. A reviewer checks the rules and compares the meaning with your original, claim by claim.
5. It gives you the edited text and up to 5 lines on what changed. For a file, it edits only the prose; code, tables and data stay untouched.

What it changes: the text you gave it. Your profile stays the same.

/vf-review: check a text against your rules

What it is for: knowing exactly which of your rules a text follows, without changing it. Draft and Edit use the same review inside their cycle.

How: /vf-review economics-en draft.md, or add the original as a third word (/vf-review economics-en edited.md original.md) to check meaning too.

What happens:

1. It runs the mechanical checks, if it can.
2. It decides which rules apply to this text and this task.
3. It gives every rule a verdict: PASS, VIOLATION, UNCERTAIN or NOT APPLICABLE. Each violation has its place, the reason, a severity and the smallest fix.
4. With the original, it checks meaning claim by claim. A change in meaning is critical, whatever the style verdicts say.

What it changes: nothing. Not the text, not the profile.

/vf-evaluate: test the skill

What it is for: finding out whether Voice Forge works for you, with five answers kept apart: is the profile in the right shape, do texts follow your rules, do they sound like you, are they well written, and do they keep the meaning.

How: /vf-evaluate economics-en, or name one part: /vf-evaluate economics-en fidelity.

The fidelity test: you give a short brief of one of your holdout texts (the agent never opens it). The agent writes versions with and without Voice Forge. vf.py blind make shuffles them under letters. You pick the one most like you, then vf.py blind score reveals which it was and logs it. After several comparisons, vf.py blind summary shows how often each source won. With fewer than about 10, it says the evidence is thin.

What it changes: files under evals/ in your voice home. Never your profile.

/vf-rules: see and change your rules

What it is for: knowing what your profile says, and adding a rule without training it first.

How:

What happens when you add a rule:

1. It checks whether a rule already covers it, in the profile or in base.md.
2. If the rule is true in all your writing in one language (for example «» in Spanish), it proposes base.md with es-only. Otherwise it uses the profile you named.
3. It drafts the full rule: the instruction, how strict it is, where it applies, exceptions, how to check it, and a mechanical check when one fits.
4. It shows the block and waits for your yes, no or rewording.
5. It writes the rule with evidence "stated" and today's date, checks the file and saves.

A dropped rule is listed as "Retired" in the profile's Notes, and its ID is never used again.

Support labels in the list: trained (from 3 or more rounds), stated (you said it), adopted (a field convention you chose), thin (little evidence), transferred (copied from another language, not yet confirmed), confirmed (transferred, then confirmed by a round).

What it changes: rules.md or base.md, only after your yes.

/vf-derive: start a profile in another language

What it is for: reusing a profile you trained well in one language to start the same kind of writing in the other language, without starting from zero. For example, explainer-en from explainer-es.

How: /vf-derive explainer-es explainer-en.

What happens:

1. It creates explainer-en and never overwrites. Each rule is copied, adapted or left out:
   • Copied: rules that work in any language, such as how you build an argument or a paragraph. They are translated.
   • Adapted: rules whose idea travels but whose wording, examples or numbers do not, such as a banned phrase or a sentence length.
   • Left out: rules that belong to the source language, such as «» quotes. They are listed in the new profile's Notes.
2. It shows you the left out list, then goes through the copied rules with you, a few at a time. You approve, reword or reject each one.
3. The new profile is provisional. Its rules are transferred until training in the new language confirms them. The agent tells you this when it uses the profile, and /vf-status shows the count ("7 of 12 confirmed").
4. Training rounds test the transferred rules first. A rule a round confirms becomes confirmed; a rule you contradict gets reworded or dropped.
5. When you are happy, the agent runs vf.py make-official.

Later changes: /vf-derive explainer-en update lists rules added or changed in explainer-es since the copy, as proposals in rules.update.md. Nothing moves without your yes.

Remember: a derived profile is a starting point, not a finished voice. You can use it right away, but keep training it.

/vf-migrate: move an old profile to the new schema

What it is for: profiles made before version 2.7.

Until you migrate, old files still work. The draft, edit and review checks print a note for them and judge their rules by reading, because the old layout has no automatic checks.

How: /vf-migrate default-en, then the other profiles, then /vf-migrate base.

What happens: it writes rules.migrated.md next to your file and never overwrites it. It keeps every rule's wording and evidence and asks you to approve the new fields of each rule. When the new file passes the check, it replaces the old one. Git keeps the old version.

/vf-learn: learn from your real edits

What it is for: learning from work you already did. For example, an agent wrote a draft, you fixed it by hand, and you want the agent to learn from your fixes. It is the same learning as training, but on real work.

Two ways to use it:

Which versions, by default. With one file and no commit, it picks the first of these that applies:

1. The draft Voice Forge wrote. When /vf-draft writes into a file in a git repo, it records that version with a commit labeled vf-draft. Learn compares it with your current file.
2. Your uncommitted edits, compared with the last commit.
3. The last two commits that changed the file.

It always tells you which two versions it is comparing before it learns. If you want others, give a commit.

What happens:

1. It gets the two versions. If someone else (a coauthor) committed changes in between, it asks which edits are yours.
2. If you already learned from this exact pair, it says so and stops.
3. It does steps 3 to 6 of /vf-train: the "passage" is the AI draft and the "rewrite" is your final version. It ignores one-time changes, such as a date or a name someone asked you to add.

What it changes: a new round file and lessons.md, after your yes. Then it saves and pushes.

/vf-analyze: build a profile from your past texts

What it is for: starting or refining a profile from texts you already wrote, such as papers, chapters, posts or a whole book.

How: /vf-analyze economics-en paper.pdf draft.docx https://myblog.com/post. It reads PDF, Word, Markdown and web pages. If your agent cannot read a format, it asks you to paste the text. Add one by one to decide one item at a time. /vf-analyze economics-en resume continues an analysis you paused.

What happens:

1. It reads everything. Long chapters are read in parts, to the end. It tells you what it could not open (an image, a page that did not extract). Tables, captions, headings and the way you introduce quotes are read too, even though the statistics leave them out.
2. It asks a few facts: about when you wrote each text ("unknown" is fine), whether others wrote or edited it, whether you still like it, and whether some texts are chapters of one project, versions of one text, or analyzed before.
3. It looks for patterns before reading your profile, so your existing lessons do not decide what it finds. It studies what each habit does for the reader, where it appears, when it changes, and where it does not happen. It does not learn your topics or opinions as style.
4. It checks how widely each pattern recurs: inside one passage, one text, one project, separate works, or works from different years. A habit seen in only one chapter can raise a question, but it does not become a lesson.
5. It compares with your profile: what confirms a rule, what adds a condition, what pulls against it, and what is new. Confirmations are listed briefly, so the time goes to what is new.
6. It labels each finding: stable voice, something you stated, a requirement of the venue, coauthor or editor style, an old habit, or too little evidence. A requirement of the venue is kept apart from a convention you choose to follow.
7. It saves the full analysis in your voice home, then shows you a short summary.
8. You decide. You see passages to check first, then candidate lessons, questions and suggestions, a few at a time or one card at a time. Each card has a short explanation, one example and a few choices. You can ask for another example, say "later", pause and resume, or reopen an item. Anything not decided stays pending in the record.

What your answers do: a fact is just a fact. "Yes, I do that" is noted, then it shows you the exact lesson wording. keep saves a candidate lesson only after you say yes to those words; it is not a rule yet. unsure, "later" or no answer changes nothing. Saying you like a whole chapter approves no single pattern. An active rule needs your yes on its full contract: after training, through a suggestion you adopt, or as a rule you state yourself (/vf-rules).

What it changes: the analysis record (always the full analysis), lessons.md (lessons whose wording you approved), rules.md (only rules whose full block you approved), the brief (conventions you agree with), and short examples you confirm as your voice. Lessons from analysis still need training rounds before they become rules. More analyses do not replace that training. Without write access, it gives you the record as Markdown and says nothing was saved.

/vf-status: see where you are

What it is for: a quick check on your progress.

How: /vf-status, or /vf-status economics-en for one profile.

What it shows: first, where your voice home is, whether it is linked to a private GitHub repo, whether auto push is on, and whether anything is waiting to be saved or pushed. Then, for each profile, whether it passes the schema check, which sections are established, whether it is PROVISIONAL (derived) and how many transferred rules training has confirmed, the number of rounds, lessons by status (candidate, promoted, rejected), and which lessons are READY to become rules. If some are ready, it offers to review them with you.

What it changes: nothing, unless you approve a promotion.

/vf-new: create a profile

What it is for: adding a new voice, such as youtube-es or memo-en.

How: /vf-new youtube-es. The name must end in -en or -es.

What happens:

1. It asks for the brief: what the voice is for, who reads or hears it, the field and venues, the main topics, and the register.
2. It creates the profile folder. If a profile with that name already exists, it stops without changing anything.
3. It writes the brief into the profile and proposes about 15 topics for you to approve.
4. It saves and pushes, then suggests two ways to start: /vf-analyze with past texts, or /vf-train.

/vf-setup: set up your voice home

What it is for: the first time you use Voice Forge, on each new computer, or to check that everything is linked.

How: /vf-setup.

What happens:

1. It asks where your private folder should live. The default is ~/.voice-forge; you can give another path.
2. If the folder already holds your voice home (for example a clone of your private repo), it keeps everything and only records the location. Otherwise it creates the folder, a git history and, if you want, a first profile.
3. It saves the location in ~/.config/voice-forge/config.json, so every agent finds it.
4. It explains why a private GitHub repo helps (backup, several computers) and asks if you want one. On yes, it creates the repo as private, checks that it is private, and pushes. It may ask you to sign in once with gh auth login. On no, everything works locally.
5. If a repo is already linked but it cannot check its privacy, it asks you to confirm. It never pushes to a repo that might be public.

If everything is already set up, it shows the current state and offers only what is missing.

What it changes: the voice home folder (only new files), the settings file voice-forge.json (auto push on by default), and the config file outside the repo.

/vf-feedback: report a problem

What it is for: keeping a record of what the skill got wrong, so it can be fixed.

How: /vf-feedback the passage was too polished. You can also just complain during a session; the agent offers to log it.

What happens: it adds a dated line, with the tool and mode, to feedback.md in your voice home, in your words. Then it saves and pushes.

What it changes: feedback.md only.

/vf-holdout: keep texts aside for tests

What it is for: setting aside a few texts you wrote that the skill never learns from. Later tests compare the skill's writing against them, to check whether training works.

How: /vf-holdout add paper.pdf, /vf-holdout add paper.pdf economics-en (to file it under a profile), or /vf-holdout list.

What happens: it copies the file into holdout/ without ever overwriting an existing one, then saves and pushes. list shows file names only. vf.py holdout check confirms no holdout paragraph also appears in your samples, rounds or analyses. No skill opens holdout texts outside a test you start.

What it changes: the holdout/ folder only.