iso-24495-code

Seven Agent Skills that support plain language writing, document audits, code, and organisationa...

审核状态：已审核Quality 72Security 60

复制安装命令

用 Codex 或 Claude 安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它先审查 Skill 页面再帮你安装。

复制前请先查看来源、License 和安全提示。

项目 README

来源文件：README.md

抓取于 2026年9月12日

ISO 24495 Plain Language Skills

Seven Agent Skills that support plain language writing, document audits, code, and organisational implementation. They apply principles inspired by the ISO 24495 Plain language series.

The skills are plain SKILL.md files with agent-neutral wording. Any tool that reads the Agent Skills format can use them.

This repository also packages them as a Claude Code plugin with an ISO 24495 output style (output-styles/iso-24495.md). Select the style with /output-style to hold every response to the core rules without relying on skill activation.

Skills

Skill	Scope
`iso-24495-1`	Core principles. Governs all user-facing output: no filler preambles, short sentences and paragraphs, active voice, scannable structure, concrete instructions.
`iso-24495-2`	Legal writing. Extends the core skill for contracts, licences, and compliance text: standardised modal verbs, no legalese, named actors, structured conditional clauses.
`iso-24495-3`	Science and technical writing. Extends the core skill for documentation, architecture, and code review: progressive disclosure, exact file citations, defined acronyms.
`iso-24495-4`	Organisational implementation (provisional). A task skill for plain language gap analysis in organisations: a process-artefact sweep, a corpus audit, a five-dimension maturity model with deterministic scoring, and an append-only audit trend. Ships TypeScript tooling run with Bun (`bun test` covered). Based on the unpublished ISO/CD 24495-4 committee draft.
`iso-24495-5`	Document design (provisional). Extends the core skill for structuring complex documents: an opening block, visual hierarchy, navigation aids, layered detail, comparisons, consistent signalling, and a signpost for the reader who wanted a different document. Ships a decision record, a runbook and a design document template. Based on the unpublished ISO/WD 24495-5 working draft.
`iso-24495-code`	Plain language in code. Applies the principles to what a person reads in source: the order units appear in, their names, what comments say, and what an error tells the reader who hits it. Measured to change how Claude structures a file, at no cost to correctness.
`iso-24495-text-audit`	User-invoked text audit. Checks a selected `.md`, `.markdown`, or `.txt` file or directory. Reports mechanical findings with locations, without deciding validity or compliance.

The core skill activates the relevant writing skills automatically. It triggers iso-24495-2 for legal content, iso-24495-3 for technical content, and iso-24495-5 for complex documents. The text audit never activates automatically.

All skills exempt internal reasoning. The writing skills preserve code blocks, commands, and logs untouched; iso-24495-code is the exception, because governing code is its subject. Technical and legal accuracy always supersede formatting rules.

Installation (Claude Code)

Add this repository as a plugin marketplace, then install the plugin:

/plugin marketplace add https://github.com/GaZmagik/iso-24495.git
/plugin install iso-24495-plain-language@iso-24495

Use the full HTTPS address as shown. The short owner/repo form makes some Claude Code versions clone over SSH, which fails without GitHub SSH keys.

Or from a local clone:

/plugin marketplace add ./path/to/this/repo
/plugin install iso-24495-plain-language@iso-24495

Installation (Codex CLI)

Codex reads the same marketplace manifest, so the plugin installs from the same address:

codex plugin marketplace add https://github.com/GaZmagik/iso-24495.git
codex plugin add iso-24495-plain-language@iso-24495

Or from a local clone, where . is the repository root:

codex plugin marketplace add .
codex plugin add iso-24495-plain-language@iso-24495

Every skill carries agents/openai.yaml, which gives Codex its display name, its short description, and the prompt Codex offers for it. Invoke a skill by name, as in $iso-24495-1, or ask for it in words.

Codex has no output style, so the same rules are a skill there: iso-24495-style holds the output style word for word, and a test keeps the two identical. It lives in codex-skills/ rather than skills/, because Claude Code scans skills/ and would otherwise offer a skill its output style already covers. Codex reads both directories, named in .codex-plugin/plugin.json.

Name the skill in your AGENTS.md to apply it to every response:

Apply `iso-24495-style` to every response.

Put that in your project's AGENTS.md or in ~/.codex/AGENTS.md. An AGENTS.md inside a plugin is ignored, so a plugin cannot apply itself.

Usage

Once installed, the agent loads the skills when their descriptions match the task. To apply one explicitly, ask for it by name, for example: "Apply iso-24495-2 to this licence text."

Invoke iso-24495-text-audit directly and supply one file or directory. The skill reads only that path and leaves every change to the user:

/iso-24495-plain-language:iso-24495-text-audit docs/policy.md

To enforce the core skill on every response, add a line to your agent's instruction file (CLAUDE.md, AGENTS.md, or equivalent):

- ALWAYS activate and adhere to the `iso-24495-1` Plain Language skill across all responses

For agents without a plugin system, copy the skills/ subdirectories into wherever the tool discovers skills.

Disclaimer

This unofficial project is not affiliated with, endorsed by, or approved by the International Organization for Standardization (ISO). The skills contain original guidance inspired by the ISO 24495 series. They do not reproduce the text of any ISO standard.

Publication status: Part 1 published 2023, Part 2 August 2025, Part 3 May 2026. Parts 4 and 5 remain unpublished drafts (ISO/CD 24495-4 and ISO/WD 24495-5). Their skills are provisional guidance from public scope statements, to be revised when ISO publishes.

Conformance disclaimer. The full ISO 24495 texts are licensed and have not been consulted. These skills are built from public principles, published scopes, and common plain-language practice.

The principles derive from the International Plain Language Federation's freely published framework. Every quantitative rule here (sentence length, paragraph density, legalese, heading depth) is this project's own proxy. No rule is a clause of any standard.

Nothing this plugin produces is a statement of ISO conformance. No certification scheme exists for ISO 24495. "Aligned" in the skills means aligned with this project's interpretation, nothing more.

Reference

Read the standard rather than this project's reading of it.

ISO 24495-1:2023, Plain language, Part 1: Governing principles and guidelines, the published standard these skills interpret. The ISO catalogue also carries Part 2 (legal writing) and Part 3 (science and technical communication).
The International Plain Language Federation's definition and framework, freely published, and the source of the four governing principles used here.
Plain Language Association International on the ISO standard, background on how the standard was drafted and what it covers.

The ISO texts are licensed, so the standards themselves cost money. Everything in this repository is built from the freely published material above.

What the engine reads

A rule can only be as right as the text it reads. So the engine parses Markdown the way CommonMark describes it: each line is matched against the containers already open, then against any container it starts. What remains is the block a rule measures. That is what lets a wrapped list item, a quotation continuing without its marker, and a heading written inside a list all be read correctly.

Measured, because a reader reads them:

paragraphs, wherever they sit;
list items, which are often the longest sentences in a document;
quotations, including GitHub alerts such as > [!WARNING];
headings, at any depth and in any container;
HTML, because its text is prose a reader reads.

Not measured, because they are not sentences:

fenced and indented code, which is a specimen rather than advice to give back to the writer;
tables, whose cells belong to a grid, except that table-header reads them;
YAML front matter, which is metadata;
a GitHub alert label, which is a label;
a task marker, which is a control rather than two words.

The parser is checked against the CommonMark reference implementation. 302 documents are recorded in skills/iso-24495-4/tests/fixtures/reference-blocks.ts, and every one that this engine reads differently carries the reason why. The reference is not a dependency: it was installed outside the repository, asked once, and its answers kept.

User-invoked text audit

The iso-24495-text-audit skill audits a selected .md, .markdown, or .txt file or directory. It uses the same rule engine as the Part 4 corpus audit. It reports each finding with its file, line, rule, and explanation.

The rules cover sentence length, sentence averages, paragraph length, legalese, and heading depth. They also cover heading-skip, heading-style, acronym-undefined, doublet, prose-enumeration, link-text, image-alt, wordy-phrase, complex-word, double-negative, filler-opening, and table-header.

The last two serve readers who hear or touch a document rather than look at it. A screen reader can list every link with no sentence around it, and an image without alternative text is silence.

The result reports zero findings when no implemented rule fires. That result does not prove the text suits its audience or purpose.

The shipped acronym list stays universal, so a technical vocabulary needs naming per project. Create .iso-24495-4/acronyms.json with the terms your readers already know:

["SQL", "SDK", "CSS", "IDE"]

An unreadable or malformed file leaves the shipped list alone, because an advisory tool must never be the reason a document cannot be checked.

The skill never runs automatically. It requires Bun and does not alter the selected text.

Directory audits skip selected or nested symbolic links and directory junctions. The result reports each skipped entry instead of reading beyond the selected path or following a cycle.

Testing policy

Run bash scripts/check.sh before you push. That script is the whole gate, and GitHub Actions runs the same file on every pull request. A failure on the server therefore reproduces locally with one command. New checks belong in the script, never in the workflow.

bun test always measures coverage. Every measured source file must cover 100% of lines and functions. Test files are excluded from those totals.

The current suite covers 100% of measured source lines and functions.

Bun reports line and function coverage only in this toolchain. We make no branch-coverage claim.

Logic-free composition roots are separate entry files. Tests never import them, so Bun excludes them from the coverage report. End-to-end tests still exercise those entries.

Every new test receives a mutation check. The implementation is deliberately broken, the test must fail, and the correct behaviour is then restored.

TypeScript style

This project follows the Google TypeScript Style Guide. It uses kebab-case filenames instead of snake_case and double quotes instead of single quotes. Both deviations match the wider ecosystem, and the repository conventions test enforces the mechanically checkable rules.

Why this project holds itself to these rules

This repository is both the tool and a user of the tool. Its shared gate audits every supported document, including this file.

That is deliberate. A plain language project that exempts itself has no claim on anyone else. The Part 4 maturity audit runs against this repository first, and its findings are acted on here first.

Roadmap

All seven skills and the output style ship in v0.6.0. What remains:

When ISO publishes Part 4: revise the provisional iso-24495-4 skill against the published text. Its committee-draft text is not public, so the current maturity model is original guidance.
When ISO publishes Part 5: revise the provisional iso-24495-5 skill against the published text.

Plain-language checks on script comments were once planned for this release. That plan is cancelled. Comments are fragments, and checking them well would cost more machinery than the advice is worth.

Licence

MIT

开发与工程内容与创作

高风险

来源需自行核对维护者身份。
未检测到明显脚本安装指令。
可能需要外部 token、网络权限或第三方服务。
存在潜在风险命令，请谨慎安装。
扫描发现：2 条。

Codex — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/GaZmagik/iso-24495.git
将 "skills/iso-24495-code" 文件夹复制到 Codex 的 skills 目录中。
重启 Codex 让新的 skill 生效。

Codex — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 Codex 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 Codex 让新的 skill 生效。

Claude Code — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/GaZmagik/iso-24495.git
将 "skills/iso-24495-code" 文件夹复制到 Claude Code 的 skills 目录中。
重启 Claude Code 让新的 skill 生效。

Claude Code — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 Claude Code 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 Claude Code 让新的 skill 生效。

Cursor — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/GaZmagik/iso-24495.git
将 "skills/iso-24495-code" 文件夹复制到 Cursor 的 skills 目录中。
重启 Cursor 让新的 skill 生效。

Cursor — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 Cursor 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 Cursor 让新的 skill 生效。

GitHub Copilot — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/GaZmagik/iso-24495.git
将 "skills/iso-24495-code" 文件夹复制到 GitHub Copilot 的 skills 目录中。
重启 GitHub Copilot 让新的 skill 生效。

GitHub Copilot — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 GitHub Copilot 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 GitHub Copilot 让新的 skill 生效。

Windsurf — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/GaZmagik/iso-24495.git
将 "skills/iso-24495-code" 文件夹复制到 Windsurf 的 skills 目录中。
重启 Windsurf 让新的 skill 生效。

Windsurf — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 Windsurf 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 Windsurf 让新的 skill 生效。

查看 SKILL.md 原文

name: iso-24495-code
description: "Plain language applied to source code (ISO 24495-1:2023 principles). Governs the parts of code a person reads: the order units appear in, their names, comments, and error messages. Applied when writing or restructuring code, not when explaining it."
metadata:
  version: "0.6.2"
  iso-standard: "ISO 24495-1:2023"
  iso-status: "published, applied by analogy to source code"

Plain language in code

Extends ISO 24495-1 to source code. Code is read far more often than it is written, so the person reading it is the reader the standard is about.

Scope. This skill governs what a reader reads: the order units appear in, what they are called, what the comments say, and what an error tells the person who hits it.

It does not govern correctness, performance, or system design. It does govern local organisation, in rules 1 and 2, because where a unit sits and how far it reaches decide what a reader must hold in their head. For maintainability weaknesses such as complexity and dead code, use a code quality skill built on ISO/IEC 5055.

This is an interpretation of ISO 24495-1 applied by analogy, not a conformance claim.

The four principles, in code

Principle	In prose	In code
Findable	The reader can find what they need	The public entry point appears first
Understandable	The reader understands it	Names say what the thing is, in the reader's words
Relevant	The reader gets what they need	A comment says why; interface documentation says what
Usable	The reader can act on it	An error names the problem and shows a safe value

Rules

1. Front-load the main path

Put the public entry point at the top of the file, before the helpers it calls. A reader opening the file meets the thing it does, then the detail, in that order. This is the code form of leading with the outcome.

Where a language forces declarations before use, put a short delegating entry point first and the implementation below it.

Measured on 30 generated implementations of one specification. Without this rule the public function landed anywhere in the file, and in half the files it was the last thing in it. With the rule it sat in the first fifth of the file every time.

The measure was chosen after those runs rather than before them, and the effect appeared in one model family but not in the two others tested. Treat it as a hypothesis with a clean separation, not a settled result.

2. One job per unit

A function does one thing that its name describes. A name needing "and" is a prompt to look, not an instruction to split. Some operations are genuinely single and named for a pair, as compareAndSwap is, and splitting those breaks them.

Helpers belong at the top level or as members of a class, rather than buried as closures inside the function they serve. A reader cannot reach a closure without reading its container first.

3. Name for the reader

A name says what the thing is or does, in the vocabulary of someone who knows the domain but not this file.
Use one name for one concept throughout. If it is a token here it is not a lexeme three functions later. Elegant variation confuses code exactly as it confuses prose.
Prefer a longer name that reads to a shorter one that must be decoded. remainingBudget beats rb.

4. A comment says why; interface documentation says what a caller needs

A comment earns its place when it records something a reader cannot recover from the code: a reason, a constraint, a rejected alternative, a bug it guards against.

Delete a comment that merely restates the line beneath it, and delete commented-out code.

This is not a rule against documentation. An interface comment tells a caller what a function returns, when it returns nothing, and what it throws. That is the reader's work being done for them, so it belongs there even when the body makes it obvious.

5. An error message serves the person who hits it

An error names the problem, shows a value it is safe to show, and where it helps, says what to do instead. Write it in the words its reader would use, so it can be acted on without opening the source.

Never put a secret in an error. A credential, token, key, password, session identifier or personal detail must not appear in a message, because messages reach logs, telemetry and screens. Name the field and describe the fault instead: API token rejected: expected 32 characters, got 8. Where you cannot show a value safely, show its shape.

A value on this path has just failed validation, so its contents are unknown. Naming the field does not make them safe: whatever the caller passed is what reaches the log. Report the format you expected and the shape of what arrived, never the value itself.

Bad:   throw new Error("invalid input")
Good:  throw new TypeError(
         `Duration must be a number followed by ms, s, m, h or d; got ${duration.length} characters`)
Good:  throw new Error(`API token rejected: expected 32 characters, got ${token.length}`)

Quote a value only where you control it, such as one you have already matched against a fixed set. Then the set, not the caller, decides what can appear.

6. Prefer the plain construction

Where two constructions are equally correct, use the one a competent reader understands without pausing. Cleverness that needs a comment to explain it has already failed.

What this skill does not do

It does not require comments. A file with no comments and clear names is fine.
It does not set a line count for a function. Use iso-5055-code-quality for size and complexity thresholds, which are measurable.
It does not apply to generated code, vendored code, or code whose layout a formatter owns.

Applying it to existing code

Change the reading order and the language. Do not restructure behaviour in the same pass, and never move code and change it at once, because the diff stops being reviewable.

发现问题？提交给管理员复核

暂无评论，成为第一个评论者吧！