Skip to content

feat: add distributable agent skills and rule-authoring workflow - #472

Open
YusukeHirao wants to merge 15 commits into
devfrom
feature/agent-skills
Open

feat: add distributable agent skills and rule-authoring workflow#472
YusukeHirao wants to merge 15 commits into
devfrom
feature/agent-skills

Conversation

@YusukeHirao

@YusukeHirao YusukeHirao commented Aug 12, 2026

Copy link
Copy Markdown
Member

概要

AI コーディングエージェント（Claude Code / Cursor）向けのスキルをこのリポジトリで管理・配布できるようにします。ガイドラインの規範をエージェントが実装時・レビュー時に参照できる形に蒸留した skills/ ディレクトリを追加し、skills CLI による配布（main ブランチが配布チャネル）を前提とした構成にしています。

変更内容

配布スキル（skills/、7 つ）

スキル 内容
dzero-tech-selection 実装レイヤー（HTML/CSS/JS）のカスケード選定基準と代表パターン対応表。実装着手前に必読
dzero-design-to-code デザインカンプ解釈の原則（数値は結果であって仕様ではない・描かれていない状態も実装対象・トークン対応付け・アセットの作業分担）
dzero-css / dzero-js / dzero-a11y / dzero-html 各技術軸の「実装規範」+「レビュー観点」。src/ の規範から lint で担保できない設計判断系を蒸留
dzero-review レビュー手順のオーケストレータ（選定妥当性 → 各軸観点）
  • 執筆規約は skills/README.md に記載（frontmatter は Cursor 互換のため name / description / license のみ、根拠のない一般論の禁止、暫定ルールの削除メモ運用）
  • stylelint で機械化できる 2 項目（トークン対応値の直書き検出、line-height の px 禁止）は linters リポジトリへの追加を提案予定で、導入までの暫定として削除メモ付きで記載

メンテナー用メタスキル（.claude/skills/rule-authoring、非配布）

新しいルール案のトリアージ（そもそもルール化すべきか → 抽象度は適正か → 恒常的原則か一時的補正か → 宛先は誰か）と置き場所分類・執筆を補助します。

ドキュメント・設定

  • src/agent-skills.md: スキル一覧・配布の仕組み・既存プロジェクトへの導入手順・更新手順のページを追加（サイドバーにも追加）
  • package.json / cspell.json: lint 対象に skills/ と .claude/ を追加し、dzero を辞書に登録
  • 既存 4 ファイルの prettier 整形ドリフトを style コミットとして分離して適用

関連

  • scaffold（frontend-env）側の対応 PR: 生成時のスキル自動導入・AGENTS.md 正本化（別途作成）
  • このブランチのマージだけでは配布は始まりません（配布チャネルは main）。main への反映後、既存案件は src/agent-skills.md の手順で導入できます

動作確認

  • yarn lint / yarn build 通過
  • npx skills@1.5.22 add <ローカルパス> --skill '*' --agent claude-code --copy -y で 7 スキルが .claude/skills/ に展開・skills-lock.json 生成・再実行での上書き更新を確認

🤖 Generated with Claude Code

@YusukeHirao
YusukeHirao requested a review from dz-ueno August 12, 2026 13:47
@YusukeHirao YusukeHirao mentioned this pull request Aug 12, 2026
Open
YusukeHirao and others added 9 commits August 13, 2026 10:10
@YusukeHirao @claude
feat(skills): add distributable agent skills for case projects
ea3841f 
Add seven skills (dzero-tech-selection, dzero-design-to-code, dzero-css,
dzero-js, dzero-a11y, dzero-html, dzero-review) distilled from the
guideline sources, distributed to case projects via the skills CLI.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
feat(claude): add rule-authoring maintainer skill
7b0c7e6 
Non-distributed skill that guides rule triage (first-principles
questions, placement classification) and authoring conventions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
docs: add agent skills introduction page
25cc9c5 
Explain the skill list, distribution mechanism, onboarding steps for
existing projects, and the update workflow.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
chore(lint): cover skills and .claude directories in lint targets
7d99f55 
Extend cspell, prettier, and textlint globs, and register the dzero
word in cspell.json.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
style: apply prettier formatting drift in existing docs
31d8057 
Formatting-only normalization produced by running yarn lint (semicolon,
table padding, trailing whitespace). No content changes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
docs: align skills:sync command with the scaffold template
f30f71e 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
refactor(skills): drop rules already enforced by linters
0760cf0 
Rules that stylelint/markuplint already enforce (BEM flat selectors,
declaration order, logical properties, value formats, heading level
skips, multiple classes) are guaranteed by the lint harness and need
not be restated as principles. Codify this policy in skills/README.md
and the rule-authoring triage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
docs: install skills CLI as a devDependency in onboarding steps
0eb6066 
Keep the version out of the scripts entry so renovate can manage it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
refactor(skills): drop mindset statements in favor of actionable rules
b2987bc 
Statements that do not change agent behavior ("write with
understanding", WCAG four-principles preamble) waste tokens per
Anthropic's skill authoring guidance (Claude is already very smart;
concise is key). Keep only project facts (WCAG 2.2 / WAI-ARIA 1.2
baseline) and convert the practical core of "prepare alternatives"
into a trigger-action rule for unexpected browser bugs. Codify the
policy in skills/README.md and rule-authoring.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao
YusukeHirao force-pushed the feature/agent-skills branch from 3566d36 to b2987bc Compare August 13, 2026 01:14
YusukeHirao and others added 6 commits August 13, 2026 11:38
@YusukeHirao @claude
refactor(skills): remove rules already enforced by linters
a0059f7 
Verified each rule against the actual @D-Zero linters configs
(stylelint-config, markuplint-config, eslint-config on origin/dev)
and empirical markuplint runs, then removed skill entries that the
lint harness already enforces:

- ID selector ban (stylelint selector-max-id: 0)
- one-component-per-file / filename-class match (@d-zero/component)
- hardcoded color / z-index values (stylelint warns to use variables;
  token rule rescoped to non-color values)
- element class format, ancestor-element crossing, c-content-main
  constraint (markuplint class-naming, verified as errors)
- native + ARIA attribute duplication (markuplint wai-aria, verified)
- br element ban (markuplint disallowed-element)
- unlabeled duplicate landmarks (markuplint landmark-roles, verified)

Also fixed a false claim: multiple component classes on one element
are NOT detected by Markuplint (verified), so the rule stays as a
skill rule without the parenthetical.

Kept rules verified as NOT lint-covered: role="none" on empty alt,
aria-hidden on meaningful img, content outside landmarks,
boolean attribute values, line-height in px.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
docs(skills): link official APG and add APG Patterns Examples reference
0d5342c 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
refactor(skills): drop review-checklist sections in favor of norms
4dff41b 
The per-skill レビュー観点 sections merely restated the implementation
norms as questions, creating a dual-maintenance burden (every norm edit
had to be mirrored). Reviews now check against the norms directly:

- remove レビュー観点 from dzero-css / dzero-html / dzero-a11y /
  dzero-js / dzero-design-to-code
- fold the one non-derivable item (never remove focus styles such as
  outline: none) into the dzero-a11y focus norm
- dzero-review now instructs checking changes against each skill's
  norms; the lint-scope note remains there as step 4
- update skills/README structure convention and the rule-authoring
  placement table accordingly

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao @claude
docs(skills): require browser verification at implementation and review
501d629 
- dzero-tech-selection: after implementing, always verify rendering,
  behavior, and interactions in a browser (not by reading code alone)
- dzero-review: add a browser verification step before the lint check

The concrete tooling is left to each project's environment
instructions (the scaffold template designates the DevTools MCP).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@YusukeHirao
Merge branch 'dev' into feature/agent-skills
84b1647
@YusukeHirao @claude
fix(repo): remove trailing period from list item to satisfy textlint
088a0ab 
The branch extends textlint targets to .claude/**, so the git skill
added on dev via #476 is now linted and violated jtf-style 1.1.3
(bullet-list punctuation consistency).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@yusasa16 yusasa16 yusasa16 approved these changes
@arktds arktds Awaiting requested review from arktds arktds is a code owner
@dz-furukawa dz-furukawa Awaiting requested review from dz-furukawa dz-furukawa is a code owner
@teppei-d teppei-d Awaiting requested review from teppei-d teppei-d is a code owner
@dz-ueno dz-ueno Awaiting requested review from dz-ueno

At least 2 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@YusukeHirao @yusasa16