본문으로 건너뛰기
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 / 1,000자

이 양식은 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의 스킬 모두 보기

이 스킬의 문제 신고