本文へ移動
cccskills
無料GitHub で公開

doc

Documentation policy — JSDoc-first; no code-derivable markdown. Use when writing or reviewing any repository documentation (JSDoc, README, markdown) or deciding where a piece of documentation belongs. Trigger keywords: documentation, JSDoc, README, markdown policy, docs, comment policy.

日本語の概要は準備中です。原文の説明を表示しています。

markuplint/markuplintスター 630(GitHub 630 + cccskills 0)

実行スコア 未検証

インストール方法を見る

含まれるファイル(1)

  • SKILL.md3.7 KB

SKILL.md(原文)

インストールする前に、エージェントに与えられる指示の中身を確認できます。

Maintain documentation under this repository's documentation policy. The implementation is the absolute source of truth.

Documentation Policy

  1. Repository markdown must contain no WHAT or HOW that is derivable from code or scripts. AI agents and contributors read code directly; restating it in markdown creates drift, not value. If a markdown section can be reconstructed by reading the code, delete it.
  2. WHY and non-derivable constraints live in JSDoc at the closest code. Spec citations, invariants, intended contracts, and known limitations belong in JSDoc on the symbol they constrain. Architecture-level WHY goes in module-level JSDoc at the owning package's entry point (src/index.ts).
  3. JSDoc scope depends on visibility:
    • Public API symbols (exported from a published package entry point — lands in .d.ts and IDE hover) MAY contain WHAT for end users.
    • Internal code JSDoc must not restate WHAT — only WHY, constraints, and non-obvious contracts.
  4. Do NOT create new ARCHITECTURE.md, docs/*.md, or similar explanatory markdown. That content belongs in JSDoc (rule 2).
  5. Exempt — rule READMEs (packages/@markuplint/rules/src/*/README.md + README.ja.md): these are website source (user-facing). Both languages must stay in sync — updating only one is a recurring mistake.
  6. Exempt — package READMEs (packages/**/README.md): npm-facing user documentation, not covered by rule 1.
  7. No plan-relative concepts in JSDoc, test names, or documentation: Phase/Step numbers, "this PR", "the old implementation", "to be introduced". Write self-contained descriptions of current behavior and intentional absences.
  8. No issue or PR numbers in code comments, JSDoc, or describe / test names. A number means nothing without opening the tracker; write the reason instead. Existing code carries many such comments — do not imitate them. The exceptions are the rule-spec test ID convention ([rule-name-issue-NNNN-001], required by packages/@markuplint/rules/CLAUDE.md), fixture file names that follow an existing pattern (issue-4054.spec.ts), and PR bodies and commit messages.

Rules

  • Use the language specified in each document
  • Do not modify the implementation when updating documentation — do not change function bodies, type definitions, export statements, or even the ordering of declarations
  • Do not include specific dependency version numbers (e.g., a version of a parser library) — versions change frequently and cause maintenance burden. package.json is the source of truth. Specification versions like ARIA 1.3 are not dependencies and may be mentioned.
  • If the intent of code or documentation is unclear, ask the user rather than guessing

JSDoc

  • Every exported function and type must have a JSDoc comment
  • Required tags:
    • @param — for each parameter; type annotation may rely on TypeScript, but a description is mandatory
    • @returns — description of the return value is mandatory
    • @template — for each type parameter; include a description
  • Do not add redundant type annotations that TypeScript already provides — describe purpose, semantics, and constraints

Final Step

After all documentation changes are complete, run yarn lint and fix any errors before committing.

What yarn lint covers differs between branches — package.json scripts.lint is the source of truth.

レビュー

まだレビューはありません。使ってみた感想をお寄せください。

コメント

ログインなしで書き込めます。使ってみた感想、質問、動かなかった環境などを気軽にどうぞ。

まだコメントはありません。最初のコメントを書いてみませんか。

送信するとすぐに公開されます。メールアドレスや電話番号などの個人情報は書かないでください。URL は 2 つまでです。

0 / 1000 文字

このフォームは reCAPTCHA で保護されており、Google のプライバシーポリシーと利用規約が適用されます。

同じリポジトリのスキル

Maintenance of the nu-validator coverage benchmark: defend the invariants (nu-only = 0, xref audit green), follow up a nu-validator upstream update (submodule bump / Docker image drift), and regression-check after markuplint rule or spec changes. Use when updating the validator submodule, when a bench refresh surfaces new nu-only entries, when excluded-ids entries go stale, or for the periodic health check. Trigger keywords: bench maintain, bench maintenance, nu update, submodule bump, validator update, bench refresh, nu-only regression, stale excluded-ids, image digest.

日本語の概要は準備中です。原文の説明を表示しています。

markuplint/markuplint6302026年10月26日 更新

Enable an existing or newly-added markuplint rule on the nu-validator bench by editing tests/external/bench/config.ts. Covers the flat-rule case (rules: { '<name>': true }) and the severity override case (rules: { '<name>': { severity: 'error' } }) that bench-virtual-rule does not. Use when a rule exists in the registry but the relevant nu fixtures stay nu-only because the rule is not enabled in the bench config, or when a rule's default severity is warning but the spec text it mirrors is a MUST / MUST NOT. Trigger keywords: enable bench rule, bench config flat rule, severity override bench, rule not flagging on bench, warning vs error in bench, escalate severity bench, no-contradictory-aria-prop bench, bench coverage missing rule.

日本語の概要は準備中です。原文の説明を表示しています。

markuplint/markuplint6302026年10月26日 更新

Set up the nu-validator benchmark environment — initialise the validator submodule, ensure Docker is running, populate the gitignored raw snapshots via yarn bench:update. Also covers Docker / nu-runner troubleshooting. Use when bench commands fail with "no snapshots found", "Docker daemon not reachable", port 28888 conflicts, or healthcheck timeouts; or when refreshing the bench after a long break. Trigger keywords: bench setup, bench Docker, validator submodule, no snapshots found, Docker daemon not reachable, healthcheck times out, port 28888, yarn bench:update first time, bench install, fresh clone bench.

日本語の概要は準備中です。原文の説明を表示しています。

markuplint/markuplint6302026年10月26日 更新

Triage one nu-only fixture from tests/external/snapshots/diff/nu-only.json by reading the spec, then drive its verdict to match-error, match-clean, or nu-over by either fixing markuplint or recording an excluded-ids.json entry. The core per-fixture operation of the nu-validator coverage benchmark. Use when a bench refresh surfaces new nu-only entries, when checking a coverage-claim ("markuplint misses X" / "over-detects Y") against the bench, or when classifying a specific fixture. Trigger keywords: nu-only, ml-only, coverage gap, bench triage, verdict, match-error, match-clean, nu-over, excluded-ids, declare nu over-detection, claim audit, audit fixture, mark-up valid per spec, spec-cited exclusion.

日本語の概要は準備中です。原文の説明を表示しています。

markuplint/markuplint6302026年10月26日 更新

Mirror a preset virtual rule (selectors under `nodeRules` in preset.html-standard.jsonc and similar) into bench/config.ts so the benchmark exercises it. Use when a new disallowed-element / similar selector lands in a preset and the matching nu fixtures remain stuck at nu-only despite the new rule existing in markuplint. Trigger keywords: virtual rule, nodeRules, disallowed-element, preset html-standard, bench config mirror, rule does not fire on bench, preset rule not exercised.

日本語の概要は準備中です。原文の説明を表示しています。

markuplint/markuplint6302026年10月26日 更新

Sync benchmark cross-reference blocks onto GitHub Issue bodies via `yarn bench:xref`, manage `tests/external/bench/issue-xref.config.ts` mappings, and run the pre-release checklist. Use when adding / removing / updating a primary or secondary mapping, when an issue closes upstream, when the xref CLI's output disagrees with what's on the issue body, or before cutting a release that touches a rule the benchmark covers. Trigger keywords: bench-xref, issue-xref, xref CLI, GitHub issue body, primary mapping, secondary mapping, umbrella block, pre-release checklist, bench-xref-audit workflow, marker version.

日本語の概要は準備中です。原文の説明を表示しています。

markuplint/markuplint6302026年10月26日 更新

markuplint のスキルをすべて見る

このスキルの問題を報告する