Positioning
This skillDesign decisionsperforms. The syntax and tool usage for actually creating a TopicsGroup with Admin MCP (topics_group-createのinputSchema, JSON for each field type) are handled by /kuroco-content-structure-creation .
Finalize this skill's deliverables (see the design deliverable template) before calling/kuroco-content-structure-creation . Adding fields to or changing the types of a content definition after creation is costly because it involves modifying already-imported data (/kuroco-app-builderdoes this design after the Phase 1 screens are finalized for the same reason). Do not skip the design and start building with syntax alone.
What to decide (in this order)
- Splitting the TopicsGroup
- Compressing the number of fields with JSON items
- How to represent master data
- How to hold classification (category/tag/relation)
- ext_slug naming policy
- Design deliverable template
1. Splitting the TopicsGroup
Check the upper limit on the number of extended items withwhoamiのsite.limits.topics_max_extension（{current, max}).maxis 999 if the site holds extended items in JSONB format, or 99 in the legacy format—do not guess。currentがmaxIf it is less thanadmin_setting-updateit can be raised with a tool (details: /kuroco-admin-mcp). If you are approaching the limit, or trying to pack data of different natures into a single definition, consider splitting while checking whether there is room to raise the limit.
| State | Decision |
|---|---|
| The number of fields is close to the limit, or is expected to keep growing | Split |
| Content of different natures (different listing methods, publication settings, or view/edit restrictions) | Split (e.g., articles and announcements) |
| Attribute variations of data of the same nature (e.g., the "feature" classification within articles) | Do not split. Express it with categories or extended item options |
If the main cause of approaching the limit is "an accumulation of simple incidental items not used for search, listing, or external integration," consider compressing them with JSON items as described in the next section before splitting.
2. Compressing the Number of Fields with JSON Items
Simple incidental information that is not used for search, listing, or external integration (filtering, sorting, integration keys)should not be divided into individual extended items but insteadjsonConsider consolidating them into a single field of type (ext_type 28). For blocks of configuration values and metadata that tend to keep growing in number of fields, this method lets you avoid consuming the upper limit on the number of extended items (see 1.).
Criteria: For each item, if the answer is YES to any of "should it be shown in a list," "will it be used for search/filtering," or "will it be a key for integration with other systems," make it an individual extended item. If all are No, it may be stored in a JSON item together with other simple incidental items.
Example: Configuration values such as "display settings (background color, layout mode, internal notes)" that are neither search targets nor list display targets should be consolidated into a single JSON item. Items used for filtering, sorting, or list display, such as "category," "price," or "publication date," should remain as individual extended items.
Constraints (noted as points not confirmed in primary sources): Standardfilter/orderNo description has been found stating that the internal keys of a JSON item can be directly filtered or sorted with a query. The filtering operations provided for individual extended items (contains/=/</>, etc.) assume values of a fixed type, and there is no description covering free-form internal structures such as the JSON type.If a requirement arises to filter by the internal keys of a JSON item contrary to these criteria, do not proceed by guessing; actually test and confirm it with Admin MCP.
3. How to represent master data: CSV table vs relation (separate TopicsGroup)
There are two ways to have "master data (common data that is repeatedly referenced)" in Kuroco.The type of the field on the calling side directly determines the shape of the API response.
CSV table + csvtable/csvtable_checkbox |
Separate TopicsGroup + relation |
|
|---|---|---|
| Entity of the master | CSV table (a separate resource outside the TopicsGroup) | A normal TopicsGroup (content) |
| API response on the calling side | The master's values are not included (only the key). The contents must be obtained by callingMaster::listseparately and joining them yourself |
id + label (e.g., subject) is returned inline（"ext_col_11": { "topics_id": 123, "subject": "タイトル" }） |
| Whether the master side can have extended items, categories, and publication control | Cannot (only CSV rows and columns) | Can (because it is ordinary content) |
| You want to filter by the master's own attributes (e.g., "only brands in a specific category") | Not possible | Possible (:R()search. There are constraints described below) |
| Cases it suits | Prefecture and industry lists, etc.,static and very simplekey/value mappings | When the master itself is edited in the admin panel, has attributes, or is used for filtering |
Principle: The field on the side that calls the master should be ofrelationtype. Use CSV tables as a lightweight alternative when it is a "truly simple fixed list".
Howeverrelationis not a "full join". What is returned by default isid + label only（module_idand one label). If you want to include all fields of the related content in the response,add custom processing to the endpoint's post-processingyou need to do so (api_methodretrieve with the model →appendreplace with.module_typeがtopics/member/inquirythe implementation differs depending on which of these). For implementation, see/kuroco-server-processing・For details, see/kuroco-api-contentSee. If you do not write this extra step into the deliverable at the design stage, you will end up with rework such as "I made it arelationbut I can't get the contents of the master".
Notes for multilingual sites: :R()Filtering related records bycan only be performed for the primary language. Even if multilingual settings are enabled, linked content is based on the primary language. If you design filtered searches using a multilingual master, state this constraint explicitly in the deliverable.
4. How to hold classifications: categories / tags / relations
There is no official Kuroco guideline on "which one should be used". The following is a design judgment derived from the actual behavior of each mechanism (
/kuroco-api-content), and is not primary information from Kuroco.
| Mechanism | Entity | Multiple selection | Suitable cases |
|---|---|---|---|
| Category | A single hierarchical ID (the API field name iscontents_type） |
Not possible (one content, one category) | Exclusive classification (e.g., article type) |
| Tag | String array | Possible | Cross-cutting labeling (e.g., keywords) |
| Relation | Reference to other content | Depends on the type | When the classification target itself has attributes, or when you want to edit the classification target in the admin screen (effectively the same judgment as "master" in 3.) |
Upper limit on the number of categoriesはwhoamiのsite.limits.topics_contents_type_cnt（{current, max}、maxis 99). If there are multiple classification axes you want to divide finely, or if the options are expected to keep increasing, lean toward tags or relations rather than categories.
5. ext_slug naming policy
For all extended items,ext_slugset. If unset, the key name isext_1format and theext_col_01format, split on a per-site basis (whoamiのsite.topics_ext_key_formatdetermined by), and the front-end mapper changes from site to site (details: /kuroco-app-builder の references/mock-contract.md). At design time, decide the slug name (match it with the field name for the application) and state it explicitly in the deliverable.
6. Design deliverable template
/kuroco-content-structure-creation Before passing it to, summarize each TopicsGroup in this format and obtain the user's agreement:
## コンテンツ定義: 記事
| フィールド名(ext_slug) | 型 | 必須 | 備考 |
|---|---|---|---|
| lead_text | text | - | |
| main_image | image | ✓ | |
| author | relation (module: member) | ✓ | 全データ取得が必要ならフェーズ3で後処理を追加 |
| brand | relation (module: topics, group_id: X) | - | マスタ=別TopicsGroup |
| prefecture | csvtable (csvtable_group_id: Y) | - | 静的固定リストのため |
| display_settings | json | - | 背景色・レイアウトモード等、検索/一覧/連携に使わない付随設定をまとめて格納 |
## マスタ一覧
| マスタ名 | 表現方法 | 理由 |
|---|---|---|
| ブランド | 別TopicsGroup + relation | 属性（ロゴ画像・説明文）を持つため |
| 都道府県 | CSVテーブル | 固定・属性不要のため |
Anti-pattern
| What you must not do | Reason |
|---|---|
| Making it a huge fixed list of options (select) even though you only want to have a master | Every time an option is added or changed, the content definition itself must be edited. Use a CSV table or a relation |
relationAssuming that doing so will return all related data |
The default is only id + label. If all data is needed, endpoint post-processing is required |
| Forcing data of different natures into a single TopicsGroup | The upper limit on the number of extended fields is reached quickly, and publish settings and view/edit restrictions can no longer be divided in detail |
ext_slugDesigning the API with numeric keys left as-is, without setting |
The key format (ext_1/ext_col_01) varies by site, and the frontend implementation becomes site-dependent |
| Lumping even fields used for search, listing, and filtering into a JSON field | Filtering and sorting by keys inside JSON is not confirmed to be supported by standard features. Put them in individual extended fields |
| Dutifully making even simple accompanying information into individual extended fields and approaching the limit | If it is not used for listing, search, or integration, combine it into one JSON field and do not strain the limit |
Related skills
| Skill | Role |
|---|---|
/kuroco-content-structure-creation |
Actually create the design decided in this skill with Admin MCP (syntax and tools).Call after this skill |
/kuroco-api-content |
API response format by field type,:R()search syntax, priority order of view/edit restrictions |
/kuroco-server-processing |
Retrieving all relation data (post-processing custom functions), external integration |
/kuroco-app-builder |
Use this skill in phase 2 of overall app construction |