{
  "markdown": "# Writer's Loop\n\nEnglish | [简体中文](README_zh.md) | [日本語](README_ja.md) | [Español](README_es.md)\n\n**AI writing that learns from your style, approvals, and edits.**\n**让 AI 写作根据你的风格、认可与修改持续改进。**\n\n[![Validate](https://github.com/xxsang/writers-loop/actions/workflows/validate.yml/badge.svg)](https://github.com/xxsang/writers-loop/actions/workflows/validate.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![No npm install](https://img.shields.io/badge/npm%20install-not%20required-brightgreen)](package.json)\n[![Memory](https://img.shields.io/badge/memory-local%20opt--in-blue)](PRIVACY.md)\n\n<p align=\"center\">\n  <img src=\"assets/writers-loop-overview.svg\" alt=\"Writer's Loop overview\" width=\"720\">\n</p>\n\nWriter's Loop is a portable writing skill for AI agents. It turns writing into\na reviewable loop — frame, plan, draft, critique, revise — and learns only from\nstyle samples you provide or approve and decisions you actually review.\n\nUse it when one-shot prompting is too fuzzy: coding plans, reports, proposals,\nproduct specs, documentation, essays, speeches, fiction, style distillation, and\ntranslation.\n\n---\n\n## One-Line Agent Setup\n\nIf you use Claude Code, Codex, Cursor, Gemini CLI, OpenCode, or another local\nagent, give it this setup prompt:\n\n```text\nHelp me install Writer's Loop from https://github.com/xxsang/writers-loop, then use $writers-loop for my writing task without saving preferences unless I explicitly opt in.\n```\n\nFor manual installation, see [docs/installation.md](docs/installation.md).\nIf your agent supports repository plugins, start with the public GitHub URL:\n`https://github.com/xxsang/writers-loop`.\n\n---\n\n## The Problem With One-Shot AI Writing\n\nMost writing prompts collapse planning, drafting, editing, and preference\nlearning into one pass. The agent guesses what you want, rewrites without\nasking, and forgets your decisions the moment the conversation ends.\n\n| Problem | Writer's Loop response |\n| --- | --- |\n| One-shot drafts guess too much | Frame the task and plan before drafting |\n| Rewrites can erase intent | Propose changes before revising |\n| AI memory can become unreliable | Learn only from reviewed decisions |\n| Style copying can leak private facts | Separate style traits from source content |\n\nWriter's Loop keeps the stages separate:\n\n| Stage | What happens |\n| --- | --- |\n| **Frame** | Understand the artifact, audience, goal, and constraints |\n| **Ask** | Ask only questions that would materially change the result |\n| **Plan** | Propose a structured plan and wait for approval |\n| **Draft** | Write once the plan is locked |\n| **Critique** | Evaluate the draft before touching it |\n| **Propose** | Name targeted changes with reason, scope, and risk |\n| **Decide** | You accept, reject, or adjust — the agent does not guess |\n| **Revise** | Rewrite only what was approved |\n| **Learn** | Record only reviewed decisions as reusable preferences |\n\nCore rule:\n\n```text\nLearn from user decisions, not from raw AI drafts.\n```\n\n```mermaid\nflowchart LR\n  A[\"Style samples you provide or approve\"] --> D[\"Reviewed signals\"]\n  B[\"Approved plans\"] --> D\n  C[\"Accepted edits\"] --> D\n  X[\"Raw AI drafts\"] -. \"not learned from\" .-> Z[\"Discarded\"]\n  D --> E[\"Reusable preferences\"]\n  E --> F[\"Better future drafts\"]\n```\n\n---\n\n## Try It In 30 Seconds\n\n```text\nUse $writers-loop for this:\n[describe the writing task]\n\nAudience: [who will read it]\nGoal: [what it should achieve]\n\nAsk only if blocked. Otherwise make a short plan, draft, and brief critique.\nDo not save preferences unless I ask.\n```\n\nFor more ready-to-copy prompts, see [docs/prompt-templates.md](docs/prompt-templates.md).\n\n---\n\n## What You Get\n\nA structured loop that keeps planning, drafting, and editing separate — so the\noutput is steerable and reviewed preferences can persist across sessions after\nexplicit opt-in.\nIncludes artifact-specific guidance for technical plans, reports, proposals,\ndocs, essays, speeches, and fiction; style distillation from your own samples;\ntranslation that preserves voice and exact technical tokens; and optional\nproject-local memory that writes only where you approve it.\n\n---\n\n## Install And Agent Support\n\nWriter's Loop is GitHub-only and public. If your agent supports repository\nplugins, install from:\n\n```text\nhttps://github.com/xxsang/writers-loop\n```\n\nFor local skill-folder installs, clone the repository, then install with the\npath or plugin flow that matches your agent.\n\n```bash\ngit clone https://github.com/xxsang/writers-loop.git\n```\n\n| Agent | Fast path |\n| --- | --- |\n| **Claude Code** | Copy `skills/writers-loop` into `~/.claude/skills/`, or use `.claude-plugin/plugin.json` |\n| **OpenAI Codex CLI** | Use the plugin flow with the GitHub URL if available, or copy `skills/writers-loop` into `~/.codex/skills/` |\n| **OpenAI Codex App** | Use the plugin flow with the GitHub URL if available, or copy `skills/writers-loop` into `~/.codex/skills/` and refresh skill discovery |\n| **Cursor** | Use `.cursor-plugin/plugin.json`, or copy the skill folder |\n| **Gemini CLI** | Run `gemini extensions install https://github.com/xxsang/writers-loop` |\n| **GitHub Copilot CLI** | Point Copilot-enabled workflows at `AGENTS.md` |\n| **OpenCode** | Follow `.opencode/INSTALL.md` |\n| **ChatGPT / hosted agents** | Paste or attach `skills/writers-loop/SKILL.md` into project instructions |\n\nFor full per-agent steps, see [docs/installation.md](docs/installation.md).\n\nNo npm install required for normal use. `package.json` is `private: true`; Node\nscripts are for validation, evals, and optional local storage tooling only.\n\n---\n\n## Writing Tool Templates\n\nWriter's Loop also ships templates for writing surfaces that do not run skills\nnatively. These are linked from the full [writing tool integration guide](docs/writing-tools.md).\n\n| Tool | Easy path |\n| --- | --- |\n| **Obsidian** | Copy `integrations/obsidian/templates/` into your vault's template folder |\n| **Logseq** | Copy `integrations/logseq/templates/writers-loop.md` into a template page |\n| **Notion** | Paste `integrations/notion/writers-loop-page-template.md` into a page |\n| **Feishu / Lark Docs** | Paste or create `integrations/feishu/writers-loop-doc-template.md` |\n| **ChatGPT / Claude Projects** | Paste the project instructions and attach the listed Writer's Loop references |\n\nObsidian quick setup:\n\n```bash\nVAULT=\"$HOME/Documents/Obsidian/MyVault\"\nmkdir -p \"$VAULT/Templates/Writers Loop\"\ncp integrations/obsidian/templates/*.md \"$VAULT/Templates/Writers Loop/\"\n```\n\nThen enable Obsidian's **Templates** core plugin and set the template folder to\n`Templates/Writers Loop`.\n\n---\n\n## Local Memory Is Opt-In\n\nWriter's Loop works without memory. Preference learning is session-only by default.\n\nIf you opt in, tools write only inside the selected project:\n\n```text\n.writers-loop/\n├── journal.jsonl\n├── prefs.md\n└── styles/\n    └── my-style.md\n```\n\n- `.writers-loop/` is never created unless you ask.\n- Never commit it to public repositories.\n- Only reviewed style packs are saved in `.writers-loop/styles/` — not raw source samples.\n\nSee [docs/local-preference-storage.md](docs/local-preference-storage.md) for\n`style:save` and other commands, and [PRIVACY.md](PRIVACY.md) for the full policy.\n\n---\n\n## When Not To Use It\n\nFor tiny one-off copy edits, a simple prompt is usually enough. Writer's Loop\nis for writing that benefits from structure, review, or reusable decisions.\n\nUsing an LLM for writing may also reduce the pleasure of writing — it can\ncompress the uncertainty, wandering, discovery, and ownership that make writing\nsatisfying. Use Writer's Loop as a scaffold, sparring partner, editor, or\ntranslator. Keep the parts of writing you value doing yourself.\n\n---\n\n## Docs\n\n| Need | Read |\n| --- | --- |\n| Quick example | [docs/demo-transcript.md](docs/demo-transcript.md) |\n| Full method | [docs/writers-loop-complete-guide.md](docs/writers-loop-complete-guide.md) |\n| Copyable prompts | [docs/prompt-templates.md](docs/prompt-templates.md) |\n| Writing tool integrations | [docs/writing-tools.md](docs/writing-tools.md) |\n| Using A Learned Style | [docs/prompt-templates.md#using-a-learned-style](docs/prompt-templates.md#using-a-learned-style) |\n| Installation | [docs/installation.md](docs/installation.md) |\n| Local preference storage | [docs/local-preference-storage.md](docs/local-preference-storage.md) |\n| Privacy policy | [PRIVACY.md](PRIVACY.md) |\n| Release checklist | [RELEASE.md](RELEASE.md) |\n\n---\n\n## Repository Layout\n\n<details>\n<summary>Show file tree</summary>\n\n```text\nskills/writers-loop/SKILL.md               Core skill instructions\nskills/writers-loop/references/            Progressive-disclosure references\nskills/writers-loop/scripts/journal.mjs    Optional local preference journal\nskills/writers-loop/scripts/style-pack.mjs Optional local style-pack storage\ndocs/                                      User-facing guides and prompt templates\n.codex-plugin/plugin.json                  Codex plugin metadata\n.claude-plugin/plugin.json                 Claude plugin metadata\n.cursor-plugin/plugin.json                 Cursor plugin metadata\ngemini-extension.json                      Gemini extension metadata\n.opencode/                                 OpenCode install metadata\ntools/                                     Maintainer validation and eval scripts\n```\n\n</details>\n\n---\n\n## Validate\n\n```bash\nnpm test\n```\n\nNo install step required. Uses only Node.js built-in modules.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Keep the skill portable, concise, and\nuseful across agents.\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n\nCopyright (c) 2026 Writer's Loop contributors.\n",
  "bytes": 9696,
  "sha": "8e845d2b2856d82ff332fb9da322a83055334c22e4a4c86bf0a7b187e1052e6f",
  "repo_slug": "xxsang/writers-loop",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_xxsang_writers_loop_4b09a5f1/readme"
}