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)
- 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.
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
- 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.
- 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.
- 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.
- 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.
- 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
- A demo video per docs page that flags itself when the UI changesVideoScreenplayClaude CodeTool free; uses your agent's quota◐ Partly testedOverseas
- AI backend code that guards against races, leaks and bad migrationsCodingbackendskillsClaude CodePostgreSQLFree; about 2× tokens per task◐ Partly testedOverseas
- An afternoon of AI work, a 3D action game you play in the browserCodingClaude CodeTripoJimengSkill free; Claude quota plus asset tools◐ Partly testedChina
- Keep a long-running AI-built project from turning into a messCodingClaudeCodexoil-delegateNeeds Claude and Codex plans◐ Partly testedChina
- Use a web app once and get an AI write-up of how it worksResearchREAClaude CodeChromeFree tools; needs Claude or Codex◐ Partly testedOverseas