clear-namingPartly tested🇨🇳 CN

Waffle's clear-naming skill reads the surrounding code first, then fixes names and explanations an agent translated too literally, such as turning in_flight into a word-for-word Chinese calque

When an agent writes or explains code in Chinese, you often get calques like 'wait for flying tasks to drain' for in_flight, and names that don't say whether something is a running task or a request awaiting a response. Chinese-community author Waffle (@Jiaoao1024, GitHub ox01024) open-sourced clear-naming (MIT): an instruction-only skill that reads definitions, call sites and state changes before it decides whether to rename and how. The same in_flight might become running_tasks if the set is already started and not finished, or requests_awaiting_response if those are outstanding HTTP calls; established terms such as HTTP, SQL and transactions can stay. Four modes: clarify this explanation only, review without editing, rename in a stated scope and update references, or merge two short principles into AGENTS.md. Install: npx skills add ox01024/clear-naming. We read SKILL.md and examples.md and checked that the tweet's examples appear in the docs; there is no runtime script to run, and we did not ask an agent to rename a real repo.

Visit site clear-naming ↗
Pricing
Free
Region
Global
Where it's from
Chinese community
Added
Nov 8, 2026
Tested on
Nov 8, 2026
Version we used
clear-naming @ 3cd4fa1 (instruction-only)
Categories
CodingWriting
Original author
Waffle @Jiaoao1024 ↗
Our test
Partly tested
Cost / time
Repo is MIT/free and instruction-only—no scripts or external services. Needs a SKILL.md-capable agent (Codex, Claude Code, etc.) subscription.
Source
X @Jiaoao1024 ↗X @Jiaoao1024 ↗GitHub ox01024/clear-naming ↗

The task

Turn an agent's calqued explanations and opaque identifiers into names and prose a reader can follow without insider metaphors—without losing technical meaning or breaking public interfaces.

Steps

  1. Install with npx skills add ox01024/clear-naming and pick Codex, Claude Code, or another host. Or git clone into ~/.agents/skills/clear-naming or .agents/skills/clear-naming in the repo. The repository root is the skill directory and ships a standard SKILL.md.
  2. If you only need this sentence explained, without a repo-wide rename, say: use $clear-naming to explain the jargon you just saw, in direct language, based on the surrounding code.
  3. For a review that does not touch files: use $clear-naming to check names, comments and explanations in the current change; suggest first, do not edit. Findings should list location, actual meaning, original wording, suggested wording and why.
  4. When you do want edits, name the scope—for example scheduler.py—keep behaviour the same, update references and run matching checks. Treat public APIs, config keys, persisted fields and protocol fields as compatibility-sensitive, not like local variables.
  5. To keep the two principles around, ask it to merge them into AGENTS.md or CLAUDE.md. If a similar section already exists it should merge in place rather than duplicate. Changing a global guidance file needs you to say so explicitly.

Prompt

Use $clear-naming to review names, comments and explanations in the current change. Suggest first; do not edit files.

What the author says

Author @Jiaoao1024: tired of agents writing calques and using in_flight for both requests and tasks, he wrote a skill that reads context before renaming or smoothing the prose. Install with npx skills add ox01024/clear-naming; his earlier pink-elephant skill can be used alongside it. The README includes a context table for in_flight and says to keep uncertainty when evidence is thin, and to treat persisted field names as a compatibility problem.

Our test

Cloned ox01024/clear-naming (commit 3cd4fa1). Read README, SKILL.md, references/examples.md and agents/openai.yaml. The repo has no test script or runtime dependency. Did not install into Codex/Claude Code or run a review/rename on real code.

What we found when we tried it:SKILL.md has standard frontmatter (name: clear-naming, MIT) and four working modes. examples.md includes both phrases from the original post: 'wait for flying tasks to drain' should become 'wait for the running tasks to finish, then exit'; 'the provider trembled and replanning failed' should become a 503 statement when that is all the logs prove. openai.yaml display name is the Chinese title 清晰命名与表达.

How to get in

Public GitHub, MIT. Docs are primarily Chinese; the SKILL.md description is bilingual. Install with npx skills add ox01024/clear-naming into Codex, Claude Code, or similar. The author also points to a companion skill, ox01024/pink-elephant.

Who it suits

Anyone who lets agents explain code in Chinese (or other non-English languages) and is tired of calques. Skip if your repo is English-only and you do not care about naming.

Pitfalls

  • It is instruction-only: quality depends on the model actually reading context. There is no bundled automated test.
  • Ordinary coding requests are not supposed to trigger a repo-wide naming audit; that limit is intentional.
  • Persisted fields, config keys and protocol fields are not local renames—old data may fail to load. Reviews should separate them from local variables.
  • We only checked the docs against the original post; we did not have an agent rename a real project.

More in this category