Skip to content
Skills Library
Programming · Building & coding

acms-theme-development

/acms-theme-development

a-blog cms(acms)のテーマを作る・継承する・ブログに割り当てる・構成を直すときの手順と判断基準。 テンプレートの探索順(子テーマ名と親テーマ名をつないだディレクトリ名による多段継承と、system へのフォールバック)、template.yaml のキー、 カテゴリー別・エントリー別テンプレートの置き方、テーマセットによる割り当て、ファイル名の先頭 _ と直接表示の禁止、 アップデートで上書きされる場所、acms.js と管理用 CSS の読み込み、テンプレート内のパスの書き換え、 表示に使われているテンプレートの調べ方(デバッグモード)、大規模サイトの設計と運用(子ブログとカテゴリーの使い分け、 下の階層のブログとの共有、開発環境から本番環境への設定の移行、ページ・モジュール・テンプレートのキャッシュ、ベンチマークモード)を扱う。 「新しいテーマを作って」「子ブログ用のテーマを分けたい」「このページのテンプレートはどれ?」 「system のテンプレートを直したい」「画像や CSS のパスが合わない」「acms.js をログイン時だけ読み込みたい」 「子ブログとカテゴリーのどちらにすべき?」「開発環境の設定を本番に反映したい」「表示が重い」と頼まれたときに使う。 a-blog cms theme, child theme, template.yaml, theme

Licence
MIT
Last repository change
12.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
1
URLs in SKILL.md
6
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

a-blog cms(acms)のテーマを作る・継承する・ブログに割り当てる・構成を直すときの手順と判断基準。 テンプレートの探索順(子テーマ名と親テーマ名をつないだディレクトリ名による多段継承と、system へのフォールバック)、template.yaml のキー、 カテゴリー別・エントリー別テンプレートの置き方、テーマセットによる割り当て、ファイル名の先頭 _ と直接表示の禁止、 アップデートで上書きされる場所、acms.js と管理用 CSS の読み込み、テンプレート内のパスの書き換え、 表示に使われているテンプレートの調べ方(デバッグモード)、大規模サイトの設計と運用(子ブログとカテゴリーの使い分け、 下の階層のブログとの共有、開発環境から本番環境への設定の移行、ページ・モジュール・テンプレートのキャッシュ、ベンチマークモード)を扱う。 「新しいテーマを作って」「子ブログ用のテーマを分けたい」「このページのテンプレートはどれ?」 「system のテンプレートを直したい」「画像や CSS のパスが合わない」「acms.js をログイン時だけ読み込みたい」 「子ブログとカテゴリーのどちらにすべき?」「開発環境の設定を本番に反映したい」「表示が重い」と頼まれたときに使う。 a-blog cms theme, child theme, template.yaml, theme

Original author description

a-blog cms(acms)のテーマを作る・継承する・ブログに割り当てる・構成を直すときの手順と判断基準。 テンプレートの探索順(子テーマ名と親テーマ名をつないだディレクトリ名による多段継承と、system へのフォールバック)、template.yaml のキー、 カテゴリー別・エントリー別テンプレートの置き方、テーマセットによる割り当て、ファイル名の先頭 _ と直接表示の禁止、 アップデートで上書きされる場所、acms.js と管理用 CSS の読み込み、テンプレート内のパスの書き換え、 表示に使われているテンプレートの調べ方(デバッグモード)、大規模サイトの設計と運用(子ブログとカテゴリーの使い分け、 下の階層のブログとの共有、開発環境から本番環境への設定の移行、ページ・モジュール・テンプレートのキャッシュ、ベンチマークモード)を扱う。 「新しいテーマを作って」「子ブログ用のテーマを分けたい」「このページのテンプレートはどれ?」 「system のテンプレートを直したい」「画像や CSS のパスが合わない」「acms.js をログイン時だけ読み込みたい」 「子ブログとカテゴリーのどちらにすべき?」「開発環境の設定を本番に反映したい」「表示が重い」と頼まれたときに使う。 a-blog cms theme, child theme, template.yaml, theme

How it works

  1. 書き始める前に
  2. テンプレートの探索順
  3. 土台のテーマとブログに割り当てるテーマを分ける(推奨)
  4. テーマの割り当て
  5. template.yaml
  6. ファイル名の先頭の と直接表示
  7. アップデートで上書きされる場所
  8. acms.js・管理用 CSS・テーマ内のパス
  9. 使われているテンプレートを調べる
  10. 大規模サイト・複数環境・性能
Original SKILL.md headings · 100 lines, 326 words
SKILL.md preview
---
name: acms-theme-development
description: >-
  a-blog cms(acms)のテーマを作る・継承する・ブログに割り当てる・構成を直すときの手順と判断基準。
  テンプレートの探索順(子テーマ名と親テーマ名をつないだディレクトリ名による多段継承と、system へのフォールバック)、template.yaml のキー、
  カテゴリー別・エントリー別テンプレートの置き方、テーマセットによる割り当て、ファイル名の先頭 _ と直接表示の禁止、
  アップデートで上書きされる場所、acms.js と管理用 CSS の読み込み、テンプレート内のパスの書き換え、
  表示に使われているテンプレートの調べ方(デバッグモード)、大規模サイトの設計と運用(子ブログとカテゴリーの使い分け、
  下の階層のブログとの共有、開発環境から本番環境への設定の移行、ページ・モジュール・テンプレートのキャッシュ、ベンチマークモード)を扱う。
  「新しいテーマを作って」「子ブログ用のテーマを分けたい」「このページのテンプレートはどれ?」
  「system のテンプレートを直したい」「画像や CSS のパスが合わない」「acms.js をログイン時だけ読み込みたい」
  「子ブログとカテゴリーのどちらにすべき?」「開発環境の設定を本番に反映したい」「表示が重い」と頼まれたときに使う。
  a-blog cms theme, child theme, template.yaml, theme set, path rewrite, acms.js, large site, multi-blog, staging, deploy, cache.
  テンプレートの記法は acms-template-acms(標準)/ acms-template-twig(Twig)、サイトの構成の判定は acms-project-triage が担う。
license: MIT
compatibility: a-blog cms Ver. 3.2 以上
metadata:
  acms-min-version: "3.2"
  status: stable
---

# a-blog cms のテーマ開発

公式ドキュメント:
- テーマ: <https://developer.a-blogcms.jp/document/themes/>
- テーマの継承: <https://developer.a-blogcms.jp/document/themes/inherit.html>
- テーマの設定(テーマセット・template.yaml): <https://developer.a-blogcms.jp/document/themes/config.html>
- パスの書き換え: <https://developer.a-blogcms.jp/document/template/entry-1443.html>
- テンプレートの探し方: <https://developer.a-blogcms.jp/document/template/entry-2313.html>

## 書き始める前に

1. `acms-project-triage` でバージョン・テーマの継承関係・Twig か標準かを確かめる。
2. どのブログ・カテゴリーにどのテーマが割り当てられているかは DB にあり、ファイルからは分からない。利用者に確認する(下の「テーマの割り当て」)。
3. 直すファイルを推測で決めない。デバッグモードで実際に使われているテンプレートを確かめる(下の「使われているテンプレートを調べる」)。

## テンプレートの探索順

- テンプレート・インクルード・テーマ内の画像や CSS は、割り当てられたテーマ → `@` の右側の親テーマ → … → `system` の順に探され、最初に見つかったファイルが使われる。`president@blog@site` なら `president@blog@site` → `blog@site` → `site` → `system`。
- 子テーマには、親と違うファイルだけを置く。親のファイルを丸ごとコピーすると、親の修正が子に届かなくなる。
- `system` は直接編集しない(アップデートで上書きされる)。変えたいファイルだけを自分のテーマの同じパスにコピーして直す。上の探索順により、そちらが優先される。

URL からどのテンプレートが選ばれるか(カテゴリー別・エントリー別を含む)は references/template-resolution.md を読む。

## 土台のテーマとブログに割り当てるテーマを分ける(推奨)

共通のテンプレートを置く土台のテーマ(例: `base`)は、どのブログにも直接割り当てない。ルートブログにも `root@base` のような子テーマを作って割り当て、ルートブログだけで使うテンプレートは `root@base` に置く。子ブログがまだ無いサイトでも同じ構成にする。

理由: URL のパスがテンプレートのファイル名と一致すると、そのテンプレートがテーマの継承をたどって探されて表示される。ルートブログに `base` を直接割り当て、ルートブログ専用のページ `campaign.html` を `base` に置くと、`news@base` を使う子ブログの `/news/campaign.html` でも同じページが表示されてしまう。`forbid_tpl_inheritance_when_path_unresolved` を on にしても、この経路は止まらない(詳細は references/template-resolution.md)。

## テーマの割り当て

| 割り当て先 | 設定する場所 |
|---|---|
| ブログ | 管理画面のブログ編集で「テーマセット」を選ぶ。テーマセットの中身(テーマディレクトリ、template.yaml を優先するか、各テンプレート)は「テーマ > テーマ設定」で作る |
| 子ブログにまとめて | 親ブログのテーマセットで「子ブログにも継承する」を有効にする。テーマセットが無い子ブログにだけ効く |
| カテゴリー | カテゴリー編集で「テーマセット」を選ぶ(「子カテゴリーにも継承する」あり)。ブログのテーマセットより優先される |
| テーマセットが無いとき | 「コンフィグ > テーマ設定(レガシー設定)」の値が使われる |

テーマ設定はルールごとにも上書きでき、ルールの条件に一致したページではその値が使われる。ファイルを置いただけではテーマは切り替わらない。

## template.yaml

- テーマ直下に置き、ページの種類ごとに使うテンプレートを指定する。テーマセットの「テンプレート選択ファイル(template.yaml)の値を優先する」が有効なときだけ読まれ、有効なら管理画面で入れた値より template.yaml の値が優先される。
- template.yaml も継承される。キーごとに子テーマ → 親テーマ → … の順に探し、最初に値があるものを使う。子テーマの template.yaml には変えたいキーだけを書けばよい。
- 本体が読むキーと既定値は references/template-resolution.md の表を見る。表にないキーを書いても本体は読まない。

## ファイル名の先頭の _ と直接表示

`_top.html`・`_entry.html`・`_member/` のように、パスのどこかの階層が `_` で始まるファイルは URL から直接表示できない(新規インストール時の `forbid_direct_access_tpl: /^_/`)。トップ・詳細・インクルード専用の部品・管理用など、URL で単独で開かれては困るテンプレートは `_` で始まる名前にする(`tpl_top` などの設定から使う分には `_` が付いていても問題ない)。古いサイトでこの設定が無い場合の既定値は off なので、`private/config.system.yaml` を利用者に確かめてもらう。

`<html>` と `<body>` を含まない部品は、ログインしていなければ別の設定(`html_format_validate`)でも 404 になる。ただし `<html>` から書いたテンプレートは、`_` で始まらなければ URL から開ける。確かめるときは必ずログアウトした状態で見る(投稿者以上でログインしていると一部の制限が外れる)。

htmx などの Ajax で読み込む部品(`/tpl/include/...` の URL や `<html>` を含まない部品)は、本体が Ajax と判定したリクエストならこれらの制限(`forbid_tpl_url_context`・`html_format_validate`)を受けない。ログアウト状態で curl などからヘッダーを付けずに取得して 404 になっても、それだけで不具合と判断しない。ブラウザの開発者ツールで実際のリクエストの結果を見るか、Ajax と判定される条件(references/template-resolution.md)を揃えて取得する。

## アップデートで上書きされる場所

本体のアップデートで置き換わるのは次の場所。ここに手を入れない。

- `themes/system/`
- `php/`(`php/ACMS/User/` と `php/AAPP/` は除く)
- `js/`、`lang/`
- `acms.js`、`index.php`
- `private/config.system.default.yaml`(設定の上書きは `private/config.system.yaml` に書く)

公式テーマ(`site` など)・自作テーマ・`extension/` は上書きされない。公式テーマを土台にするときも、公式テーマを直接直すより子テーマを作るほうが、公式テーマの更新を取り込みやすい。

## acms.js・管理用 CSS・テーマ内のパス

- `acms.js` は Js モジュール(標準テンプレート)か `module('V2_Js')`(Twig)で `<head>` 内に出力する。
- ログイン中の投稿者以上には、テンプレートに書かなくても本体が `acms.js` と管理画面用の JavaScript を差し込む。一方、ログインしていない閲覧者には、テンプレートで Js モジュールを出力したときだけ組み込み JS が読み込まれる。
- そのため Js モジュールを `Touch_SessionWithContribution` などで囲んでログイン時だけにすると、閲覧者の画面で組み込み JS に頼る機能(`form.js-validator` のフォーム入力チェック、画像のライトボックス、遅延読み込み、地図など)がすべて動かなくなる。この構成にするなら、それらをテーマ側の JavaScript で用意すると決めてからにする。
- 管理用 CSS(`acms-admin.min.css`)は、公式テーマと同じくログイン中だけ読み込んでよい。

テンプレートに書いた画像・CSS・JavaScript のパスがどう書き換わるか、組み込み JS の詳細は references/assets-and-javascript.md を読む。

## 使われているテンプレートを調べる

1. 管理者ユーザーのユーザー編集で「モード」を「デバッグモード」にしてもらう(Ver. 3.1 以降。その管理者だけに効くので、サイト全体の設定を変えなくてよい)。
2. ログインした状態で対象ページを開くと、管理ボックスに表示中のテンプレートのパスとテーマセット名が出る。
3. ページのソースを見ると、インクルードしたファイルのパスが `<!-- Start of include : source=... -->` の HTML コメントで出る(Twig の `include` は Ver. 3.2.15 以降)。
4. 「デバッグモード & ベンチマークモード」にすると、ページ下部に読み込んだテンプレートの一覧も出る(標準テンプレートのインクルードが対象)。

ログアウトした状態の表示を確かめたいときは `config.server.php` の `DEBUG_MODE` を使う方法もあるが、このファイルは DB の接続情報を含むため、エージェントは開かず、利用者に変更を依頼する。

## 大規模サイト・複数環境・性能

子ブログやカテゴリーが多いサイトの構成、開発環境から本番環境への反映、キャッシュや重いページの調査を扱うときは references/large-site.md を読む。特に次の 3 つは誤りやすい。

- テーマ(ファイル)と、テーマセット・モジュール ID・フォーム ID・ルール(DB)は別々に運ぶ。公開後は本番の DB を開発環境の DB で上書きしない。
- コンフィグのインポートは、そのブログの設定を足し合わせず丸ごと入れ替える。
- テンプレートキャッシュはファイルを書き換えても消えない。本番に反映したらテンプレートキャッシュとページキャッシュをクリアする。

## テーマを新しく作るとき

1. 一から作らず、公式テーマ(<https://developer.a-blogcms.jp/document/themes/official-2025.html>)か既存のテーマを親にした子テーマで始められないか検討する。
2. 土台のテーマと、ブログに割り当てる子テーマを分ける(上の推奨)。
3. 標準テンプレートと Twig のどちらで書くかを決める。既存のテーマを継承するなら親に合わせる(Twig は template.yaml の `tpl_twig: enabled` かテーマ設定で有効にする。記法は acms-template-twig)。
4. ブログ・カテゴリーへの割り当てはテーマセットで行うよう利用者に伝える。
Files in this package (5)
  • SKILL.md 13 KB
  • evals/scenarios.json 9 KB
  • references/assets-and-javascript.md 6 KB
  • references/large-site.md 18 KB
  • references/template-resolution.md 9 KB

Versions

The database has no other skills named acms-theme-development.

Database snapshot: 13.11.2026 · package version 66f8563b8eca (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100acms-static-to-theme
    静的な HTML サイト(手書きの HTML、Vite・webpack・静的サイトジェネレーターなどのビルドの成果物、LP 1 枚から多言語のサイトまで)を a-blog cms(acms)のテーマにする「CMS 化」の作業を、環境の確認 → 標準テンプレートか Twig かの決定 → scripts/inventory.sh による棚卸し → ページと要素の機能への割り当て → テーマの作成 → 動的な部分の置き換え → 管理画面での作業の一覧 → 確認、の固定の順序で導く。 共通部分の切り出し、アセットのパス(相対・ルート相対・CSS の中の…
  • 89wp-theme-development
    WordPress theme code review and block theme development patterns for WordPress 6.6+. Use when reviewing theme code, auditing theme.json schema, checking template hierarchy, validating block templates, analyzing global styles, verifying style variations, reviewing template parts,…
  • 95engineering-cms-developer
    Use when Codex should act as the CMS Developer specialist from Agency Agents. Drupal and WordPress specialist for theme development, custom plugins/modules, content architecture, and code-first CMS implementation
  • 100hugo-theme
    Build, customize, and debug advanced Hugo CMS themes — template architecture, asset pipeline (CSS/JS/image processing), shortcodes and render hooks, page bundles, cover images, Hugo Modules, performance, SEO, and CI/CD. Use when working on a Hugo theme or site template layer. Do…
  • 90wp-theme-development
    WordPress theme review for Codex. Use when reviewing block themes, classic themes, or hybrid themes for theme.json structure, templates, template parts, style variations, global styles, and FSE patterns.
  • 100wordpress-theme-to-emdash
    Port a WordPress theme's design and template behavior to an EmDash-powered Astro site. Use for theme migrations, design matching, PHP-template conversion, and CMS wiring. Do not use for WordPress plugin behavior that does not affect the site theme.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.