agentleFS
open-thoughtsopen-thoughts/OpenThoughts-Agent/.agents/skills/writing-style/SKILL.md

writing-style

Skill309 starsChanged 4 months agoApache-2.0View on GitHub

Marin house writing style. Use when drafting or revising Marin-authored prose, including commit messages and GitHub PR, issue, or comment text.

31 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use changeset-scope, skill-prefixes and 5 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • timmo001Skill

    changeset-scope

    Keep all scoped code work contained to the user-defined changeset. Use for implementation, fixes, diagnosis, refactoring, cleanup, and review when explicit instructions, named files, diffs, branches, pull requests, or injected work scopes define the boundary.

    Also in 3 projects that use this

  • timmo001Skill

    skill-prefixes

    Name skills with an owner prefix so they do not collide with shared, imported or other repositories' skills. Use when creating, renaming, importing or reviewing a skill name, especially for repository-local or tool-owned skills.

    Also in 3 projects that use this

  • NVIDIASkill

    testing

    Run Python and Rust tests for physicsnemo-curator using uv + pytest with coverage reporting via pytest-cov, and cargo-nextest for Rust tests. Includes benchmark workflows with pytest-benchmark and criterion.

    Also in 3 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 4 projects that use this

  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 3 projects that use this

  • +2 more from timmo001

The file

Show its rules and text

We split this skill into the rules it gives an agent

31 rules. 0 are common, 29 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 29 edited versions we read keep these.

  • 29

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Start here for any non-trivial Marin-authored text.

    line 10
  2. Distinctive:

    Read blog-posts.md for public explainers and blog posts.

    line 14
  3. Distinctive:

    Read reports.md for technical reports aimed at peer researchers outside Marin.

    line 15
  4. Distinctive:

    Read tutorials.md for learning-oriented documentation that introduces Marin.

    line 16
  5. Distinctive:

    Read reference-docs.md for precise usage docs aimed at readers who already know Marin.

    line 17
  6. Distinctive:

    Read issues.md for standard OSS issues and experiment issues.

    line 18
  7. Distinctive:

    Read pull-requests.md for commit messages and PR titles and bodies.

    line 19
  8. Distinctive:

    Read discord.md for Discord summaries and tactical replies.

    line 20
  9. Distinctive:

    Read ai-writing-donts.md for the final prose-only review pass that strips generic AI-writing patterns.

    line 21
  10. Distinctive:

    Write from the stance of a rigorous, open-science lab building frontier-level foundation models.

    line 26
  11. Distinctive:

    Treat process as part of the work.

    line 27
  12. Distinctive:

    Keep an open door, not a megaphone.

    line 34
  13. Distinctive:

    Use technical language where it helps, but keep the tone natural and direct.

    line 40
  14. Distinctive:

    Remove hype, marketing copy, and launch-tweet energy.

    line 52
  15. Distinctive:

    Use emoji very sparingly: for communication, not flair.

    line 53
  16. Distinctive:

    Remove grand claims that outrun the evidence.

    line 54
  17. Distinctive:

    Avoid AGI rhetoric and speculation.

    line 55
  18. Distinctive:

    Avoid adjectives that try to do the work of numbers.

    line 56
  19. Distinctive:

    If a sentence sounds like a product announcement, rewrite it.

    line 57
  20. Distinctive:

    Prefer the simplest framing that is still correct.

    line 62
  21. Distinctive:

    Treat the reader as a capable collaborator.

    line 64
  22. Distinctive:

    Default to transparency. Include what worked, what failed, what surprised you, and what you would try next.

    line 65
  23. Distinctive:

    Do not force these patterns into short-form media that do not benefit from them.

    line 73
  24. Distinctive:

    Do not assume deep specialization by default.

    line 78
  25. Distinctive:

    Add detail only when it helps the reader reproduce, evaluate, or act.

    line 80
  26. Distinctive:

    Prefer short, direct sentences.

    line 84
  27. Distinctive:

    Follow with method or explanation.

    line 86
  28. Very specific:

    Prefer phrases like we found, this suggests, in practice, and one limitation is.

    line 88
  29. Very specific:

    Avoid phrases like clearly, obviously, groundbreaking, and state-of-the-art unless you define and defend them.

    line 89
  30. Distinctive:

    Do one editing pass that looks only for generic, over-smoothed, LLM-sounding prose.

    line 93
  31. Distinctive:

    Write clearly, honestly, and with enough evidence for the work to stand on its own.

    line 105

“Common” is measured: kept by at least 6 in 10 of the 29 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- Vendored from marin-community/marin-style v0.3.0 — do not edit; re-run `marin-style sync`. -->

Marin House Style

Start here for any non-trivial Marin-authored text. This file is the common layer; then read the medium-specific file that matches the deliverable.

Read The Right File

  • Read blog-posts.md for public explainers and blog posts.
  • Read reports.md for technical reports aimed at peer researchers outside Marin.
  • Read tutorials.md for learning-oriented documentation that introduces Marin.
  • Read reference-docs.md for precise usage docs aimed at readers who already know Marin.
  • Read issues.md for standard OSS issues and experiment issues.
  • Read pull-requests.md for commit messages and PR titles and bodies.
  • Read discord.md for Discord summaries and tactical replies.
  • Read ai-writing-donts.md for the final prose-only review pass that strips generic AI-writing patterns.
  • Apply this file first, then apply the medium-specific file. If a piece spans multiple media, keep the stricter rule.

Hold The Marin Positioning

  • Write from the stance of a rigorous, open-science lab building frontier-level foundation models.
  • Treat process as part of the work. Experiments, decisions, and mistakes all belong in the record.
  • Let the work speak. Do not substitute tone for evidence.

Keep The Core Vibe

  • Be sober, not flashy.
  • Project quiet confidence.
  • Keep an open door, not a megaphone.
  • Stay practical and hands-on.
  • Aim to be helpful and respectful.
  • Assume a baseline familiarity with ML systems.
  • Don’t dilute discussions to accommodate every level of experience. (Different media will be intended for different levels of experience.)
  • Don’t be overly formal; write like a technical peer, not an academic paper or a product blog.
  • Use technical language where it helps, but keep the tone natural and direct.

On Voice

The above defines the default voice; we allow some flexibility by author. These rules are stricter for agent-written text than for human-written text.

Researchers need not suppress their own voice. Some personality is fine, especially in retrospectives, blog posts, and narrative writeups, as long as the writing stays concrete, honest, and technically disciplined.

Agents should err toward more discipline. When reviewing human prose, allow deviations and flourishes that do not conflict with core Marin values.

Enforce Hard Rules

  • Remove hype, marketing copy, and launch-tweet energy.
  • Use emoji very sparingly: for communication, not flair.
  • Remove grand claims that outrun the evidence.
  • Avoid AGI rhetoric and speculation.
  • Avoid adjectives that try to do the work of numbers.
  • If a sentence sounds like a product announcement, rewrite it.

Follow The Writing Principles

  • Show results instead of claiming them. Prefer concrete numbers, examples, and observed behavior.
  • Prefer the simplest framing that is still correct.
  • State uncertainty plainly. Use phrases like we think, preliminary results suggest, or this seems to break down when... when warranted.
  • Treat the reader as a capable collaborator. Do not condescend or over-explain basics.
  • Default to transparency. Include what worked, what failed, what surprised you, and what you would try next.
  • Cite the relevant prior work and artifacts. This includes Marin experiments, reports, issues, PRs, papers, and other external work when they materially inform the piece.

Add Structure For Longer-Form Writing

  • For longer-form writing, include an easy-to-scan doc-level TL;DR near the top.
  • For longer-form writing, add section-level takeaway lines or short TL;DRs where they help readers navigate.
  • Do not force these patterns into short-form media that do not benefit from them.

Set Audience By Default

  • Assume the reader works in ML or LLMs unless the medium says otherwise.
  • Do not assume deep specialization by default.
  • Introduce non-standard terms before using them heavily.
  • Add detail only when it helps the reader reproduce, evaluate, or act.

Use Sentence-Level Defaults

  • Prefer short, direct sentences.
  • Lead with the result or takeaway.
  • Follow with method or explanation.
  • End with caveats, limits, or open questions when needed.
  • Prefer phrases like we found, this suggests, in practice, and one limitation is.
  • Avoid phrases like clearly, obviously, groundbreaking, and state-of-the-art unless you define and defend them.

Review For AI-Writing Tells

Do one editing pass that looks only for generic, over-smoothed, LLM-sounding prose. Then apply ai-writing-donts.md as the detailed checklist for what to remove or rewrite.

Run A Quick Self-Check

  • Did you include concrete evidence?
  • Did you remove hype language?
  • Would this sound normal spoken aloud to a colleague?
  • Did you overstate certainty or scope?
  • Did you remove generic AI-writing templates and filler?

Keep The One-Line Summary

Write clearly, honestly, and with enough evidence for the work to stand on its own.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.