SuperAPI AI Directory
Partner中文AI newsFavorites
Skillskuroco-spec-writer

kuroco-spec-writer

Coding & development

View repository

Updated 10-15 23:42

About this skill

Kuroco Specification Generator (Admin MCP)

Overview

Admin MCP のRead-only tools onlyto collect the actual configuration of a Kuroco site, and references/template.md to generate a full set of specifications in Markdown + Mermaid. Because the implementation (actual configuration) is used as primary information, unlike a hand-written specification, it does not diverge from the real thing.

Scope of this skill Out of scope
Generation of an as-built specification from the actual configuration (main chapters = content definitions, APIs, authentication, workflows, custom handlers, forms + other modules used on that site) Changing configuration (not performed by this skill. For changes, switch to /kuroco-admin-mcp and carry them out with user approval)
Visualization of structure using ER diagrams, sequence diagrams, state transition diagrams, and flowcharts Security risk assessment (→ /kuroco-security-audit）
Bundling of machine-readable definition files (OpenAPI 3.1.0 for APIs and raw responses for content definitions. → Machine-readable definition files） Duplication/migration to other sites using the definition files (up to reading and saving. Importing is /kuroco-content-structure）
Conversion to PDF + zip (scripts/build-pdf.mjs, local execution environment only) Specification of frontend implementation code (if a repository exists, produce it separately from the code)
Interpretation of edited specifications and presentation of a diff plan (→ Applying changes from the specification） Executing write operations for applying changes (follow the conventions and approval flow of/kuroco-admin-mcp , etc.)

Minimal flow:

  1. Agreement on scope (target site, readers, output destination, whether PDF is needed)
  2. whoami Finalize the connection context with
  3. Determine the modules in use and collect configuration (read-only, parallelization allowed)
  4. Generate according to the template + save machine-readable definition files → inspection → (optionally) PDF conversion

Prerequisite: Connection

For the Admin MCP connection, authentication, and scoped URL specifications, refer to /kuroco-admin-mcp . In this skill, only the following is observed.

  • /readonly A scoped URL with Because write tools do not appear in the list, accidents can be structurally prevented 
    https://{site}.g.kuroco.app/direct/rcms_api/admin_mcp/x/all/readonly
  • Since the specification looks across modules, all is often appropriate for the scope
  • Even if the connected server has a writable scope,this skill calls only read-only tools while it is running

Output structure

1 Definition = 1 page split structureis the default. Putting everything in one file makes it too long to read.

spec/                      # 出力先ディレクトリ（Step 1 で合意する）
├── README.md              # 目次・サイト概要・全体構成図（flowchart）
├── contents/
│   ├── _index.md          # コンテンツ定義一覧表 + ER図（erDiagram）
│   └── {ページキー}.md      # 1定義 = 1ページ（概要・項目表・公開制御・関連API）
├── functions/
│   ├── _index.md          # カスタム処理・バッチ一覧表
│   └── {static_sysnm}.md  # 1処理 = 1ページ
├── api.md                 # APIエンドポイント一覧
├── auth.md                # 認証・会員グループ（sequenceDiagram）
├── workflow.md            # 承認フロー（stateDiagram-v2）※フロー未使用なら作らない
├── forms.md               # フォーム一覧 ※フォーム未使用なら作らない
├── {module}.md            # 上記以外で使われているモジュールの一覧表（Step 3 で判明した分だけ）
└── schema/                # 機械可読な定義ファイル（人間向けの章ではなく、機械可読の原本）
    ├── openapi/
    │   └── api{api_id}_{api名}.json  # api-export_openapi の OpenAPI 3.1.0
    └── contents/
        └── {ページキー}.json        # topics_group-get のレスポンス（項目定義の原本）

This is not a fixed chapter structure.The modules used are determined by the count check in Step 3, so if there are CSV tables (master data), site constants, email templates, etc., add pages.

The template and listed items for each page are references/template.md as correct.

Criteria for deciding splits:

The judgment axes are the two: "Is it used」と「Is it within scope. Do not decide based on only one:

Within scope Outside scope
Used Create a page (follow the granularity table below) Do not create a standalone page. List it in the module list as a single row "exists but out of scope." If given a standalone page, it will be misread as an in-scope element
Not used Do not create a page, list one row "unused" in the table of contents List one row "out of scope (not collected this time)" in the table of contents.Do not write "unused"

Page granularity:

Target Handling
Content definitions, custom processing/batch Always 1 item = 1 page. However, if there are 3 or fewer applicable items, _index.md may be merged (increasing files makes it harder to read).Even after merging, keep the page key correspondence table and item table—if they disappear, there will be no resolution target in round-trip operations. Omit the ER diagram only when there is not a single relationship, and write one line explaining why it was omitted
API list, authentication, approval flow, forms, other modules Always 1 file(one concern for the entire site). Split only modules that are numerous and require definitions, in the same way as contents/

How to decide page keys (file names, diagram node names)

Kuroco content definitions do not have ASCII identifiers. What they have is topics_group_id(numeric) and group_nm(mostly Japanese), andext_slug はitemis an identifier for items, not an identifier for definitions. Therefore, for file names and ER diagram node names, use thepage keyassigned on the specification side.

  • The format is fixed as tg{topics_group_id}_{名前} fix with(example: tg12_product). The name part is a convenient name decided on the specification side, and the only thing that can point to the entity is topics_group_id —byalways including it, no matter whether you look at the file name, diagram node name, or theschema/ file name, you can reach the actual definition, and uniqueness is also guaranteed by topics_group_id guarantees
  • The name part is determined in the following priority order: ① the end of the path of the API endpoint that returns that definition (/rcms-api/3/requests → tg7_requests） ②group_nm English translation/romanization of (購買申請 → tg7_purchase_requests). If neither can be determined, tg{topics_group_id} alone is sufficient
  • ASCII lowercase + _ only. Use the same string for the Mermaid node ID and the file name
  • The name part is a convenient name within the specification document and is not a Kuroco-side setting(the actual value is only the leading topics_group_id ). Write that fact in one sentence in the heading of the correspondence table in contents/_index.md, and also place a column for topics_group_id in the correspondence table. If you do not write it, readers will misread it as the identifier of the actual setting, and in round-trip operation a key change will be misunderstood as a "rename request"
  • Apply the rule of including the ID to other resources as well. schema/openapi/ The file name of api{api_id}_{api名}. Custom processes and batches have actual identifiers (static_sysnm), so do not assign numbers and use them as is
  • Assign numbers only to definitions that have pages. For definitions that merely mention a name as a reference target (such as out of scope), do not assign a page key, and indicate them bytopics_group_id and name

Procedure

Step 1: Agree on scope

Confirm with the user before execution (do not start by guessing):

  1. Target site — which one if there are multiple connected Admin MCP servers
  2. Target scope — whether the entire site (default) or only some functions/definitions. If the request text narrows the scope, follow it
  3. Readers and level of detail — whether for developers (include setting values and identifiers; default) or for non-engineers (centered on business language, with setting values only as key points)
  4. Output destination directory — by default, spec/directly under the working directory. If existing files are present, check their contents before overwriting
  5. Whether PDF + zip are needed — if needed, carry out through Step 6 (Chrome is required in the local execution environment)

Degradation rules for partial scope(the default chapter structure assumes the entire site, so explicitly degrade it):

  • _index.md The population of the list ofonly the target scope. Do not make it a list of the entire site
  • For out-of-scope definitions and processes, only when they are referenced, separate them into a separate table and clearly state "out of scope", and write onlytopics_group_id and the name.Do not assign page keys(a key with no page has no resolution target in round-trip operation)
  • Write out-of-scope chapters in the README table of contents as **"out of scope (not collected this time)"**, not as "unused" or "unconfirmed" (see the status categories below)
  • Even if the scope is narrowed, include the site overview (README) and the APIs and authentication used by the target definitions. Otherwise the document will not be readable on its own

If you cannot ask the user (e.g., non-interactive execution), do not stop generation. Howeverthe default value is the lowest priority, and it is determined in the following order of priority:

  1. Explicit statement in the request(e.g., "the handover target is a non-engineer" → for non-engineers. Do not override with the default value)
  2. What can be determined from context(e.g., one connected Admin MCP → that is the target site)
  3. Default value(target site is whoami の site, detail level is for developers, output destination is spec/, no PDF)

List the assumptions adopted and the basis on which each was determined at the beginning of README.md as "Assumptions (Unverified)".

Step 2: whoami to finalize the connection context

The first tool to call is whoami。 site（site_key / env / site_url / api_url) to detect mix-ups of the target site, and use it as the primary source for the site overview and overall architecture diagram in the README.permissions serves as the basis for distinguishing "was able to retrieve / was not able to retrieve".

Step 3: Determining collection targets and collecting

The chapter structure is derived from the tool list. Do not keep a list of modules in this skill——Admin MCP has over 250 tools, and any enumerated table will inevitably be incomplete and outdated. Let the tool list side guarantee comprehensiveness.

For partial scopes, also reduce the scan(align with the reduction rules in Step 1). For site-wide scope, apply 1–3 below to all modules.

The determination of "necessary" iswhether it affects the truth or falsity of the description in the target chapterand is decided as follows:

  • Check the count as well: Modules for which whether the count is 0 changes how the target chapter is written. Examples——approval flows (whether "no approval" can be written), CSV tables (reference destinations of master items), categories/tags (presence or absence of a classification section)
  • Do not call: Modules that do not affect the description of the target chapter. Treat them as "out of scope (not collected this time)", anddo not write that they are unused(since they were not called, this cannot be asserted)
  • If in doubt, call it. The harm of an incorrect "none" is greater than the cost of one read
  1. In the tool list, {module}-list among theonly those that return configuration (definitions/settings)pick out, andcnt=1 check the count with (pageInfo.totalCnt). Exclude: logs, history, analytics (*_log-list / *_history-list / *_analytics-list / login_failed-list etc.), actual data (member-list / topics-list / inquiry_submission-list etc. Do not use for anything other than checking counts), usage/billing (usage-*）。These are not the subject of the specification(operational status is /kuroco-api-performance-review, risk assessment is /kuroco-security-audit）
  2. For modules with 1 or more, by defaultone list tableis put into the chapter (modules that do not fall under the main chapters below can also be picked up here. Examples: csvtable(master data),site_const・mailtemplateedit・tag・magazine・comment_module・spider etc.)
  3. Only the main chapters are explored in depth.For tool names, the correct ones are those that actually exist in the connected list, and the following are typical examples. Do not guess and call names that are not in the list
chapter Typical tools Key points for deeper exploration
README (overview, overall structure) whoami / site_setting-get site（site_key / env / site_url / api_url）・limits
contents/ (content definitions) topics_group-list → each definition topics-describe, and only the missing parts topics_group-get The item table can be assembled with topics-describe . relation reference target group_id・searchable・item group parent-child structure・only definitions that require definition level settings topics_group-get is also called (schema/contents/ If the policy is to keep the original in , it is required for all definitions). Which key becomes which column,topics-describe The four details that does not return are references/field-mapping.md is correct.Do not discard the called response even after writing the item table; save it in schema/contents/ save to（→ machine-readable definition file）
api.md (API list) api-list → api_uri-list（uri_data_only=true) + for each API api-export_openapi For the authentication method, config.security、CORSは cors。model_method_params.topics_group_id is the target definition for that endpoint(basis for the "target" column).model_classpath+model_method / summary / cache_settings / open_flg。api-export_openapi（api_id required / format は json default・yaml allowed) returns OpenAPI 3.1.0 as is, so do not transcribe parameters or response schemas into the list table; save them in schema/openapi/ save to（→ machine-readable definition file）
auth.md (authentication, member groups) group-list / site_setting-get super_flg(1=privileged)・cnt(number of members)・limited_ip。group_kbn is the setting value for administrative privileges (Do not perform validity checks→ security-audit）
functions/ (custom processing, batch) custom_function-list（columns specification required）/ batch-list The identifier is static_sysnm, and the trigger is trigger_sysnm

For modules other than those, whether details beyond the list table are needed should be judged from the reader and purpose, and confirmed with the user. The meaning of module-specific fields is /kuroco-docs and each tool's inputSchema・response *_vectors(e.g., api-list の api_config_vectors.security.options contains the key→Japanese label mapping) is correct.

Mapping between item table columns and read keys (topics-describe の field_map / topics_group-get の formData can be assembled from either ) is references/field-mapping.md is correct. Do not fill in by guessing; always refer to it——The meaning cannot be read from the key name, and the accuracy of round-trip operation depends on the item table.

Rules during collection:

  • Use only read-only tools.create / update / delete / bulk_* Do not call at all
  • Independent reads may be issued as multiple tool calls simultaneously and executed in parallel
  • For list retrieval, cnt limit the number of items with ,pageInfo.totalCnt understand the total count with and then retrieve only what is needed (totalPageCnt If there are 2 or more, send pages. Look at only the first page and do not write "all")
  • Before calling, inputSchema narrow down with the argument (columns / cnt / *_only) and use what is available. What the specification needs is definitions, not the body text or source. Examples that were large in actual measurement:
    • custom_function-list: by default returns the full Smarty source (contents) for all lines.columns で static_id / subject / static_sysnm / trigger_sysnm / open_flg / static_category_id / memo narrow down to
    • api_uri-list: uri_data_only=true add (if not added, the full parameter definitions for each endpoint are attached)
    • topics_group-get: there is no argument to narrow down with, andlatestRow と formData contains duplicate returns of the same content plus Smarty templates (search_template_* / custom_css / custom_js).For tools that cannot be narrowed down, once 1 record is fetched, finish writing that page before fetching the next(do not start writing after accumulating all records)
  • Distinguish module states into 4.If the reason "there is no page" is not conveyed to the reader, everything will be read as "there is no function"
    • list: [] + totalCnt: 0 and errors: [] → unused(you may conclude this. Do not create a page and put "unused" in the table of contents)
    • The module's tools are not in the list → unconfirmed (tools not visible). Because it is affected by scope and permissions, it is not the absence of a function
    • errors is not empty → unconfirmed (reason). Do not confuse with 0 records. Even in a response treated as successful, if errors is present, the record was not fetched
    • The tool is visible, butit was not called because it is outside the requested scope → out of scope (not collected this time). Write "intentionally not fetched". If silently dropped, it looks the same as unused
  • Do not silently drop items that could not be fetched. Whatever the reason, such as insufficient permissions or an oversized response, write "unconfirmed" and the reason on the relevant page. If you do not write it, the reader will understand it as "does not exist"
  • When including the count, call with topics-list を cnt=1 + columns=["topics_id"] , andpageInfo.totalCnt read only (the contents of the records are unnecessary for the specification)

Step 4: Generation of the specification

references/template.md Write each page according to the template in . The core policy for generation:

  • At the beginning of each page, kuroco-spec always include a metadata comment(format is template.md). In the round-trip operation where the user edits the specification and asks AI to reflect it, use it to resolve the ID of the target resource. Because it is an HTML comment, it is not visible to the reader
  • Record the names of the tools actually called to write that page——the metadata comment's tools must always be included, and for developer-level detail, also in the source line at the end of the page. Since it is kept on the specification side, this skill does not need to hold a list of modules, and accurate sources remain per site. In addition:
    • At the time of reflection, re-fetching the current state makes it clear from the specification which tools to call again
    • Readers can trace back to the original (admin screen, API). A specification whose setting values have unknown origins cannot be reviewed
    • Only read tools that were actually called may be written. Do not write tool names that were not called or write tool names for reflection (there is no verification, and tool names change depending on the connection scope)
  • Restore the intent, not just a list of settings. Setting values are listed in parentheses as evidence (when at developer-level detail). Content definition's secure_level / writer_groups / contents_type_cnt The correspondence for rephrasing etc. into business language is references/field-mapping.md Section 4 of is authoritative
  • ER diagrams and node names in diagrams usepage key, and item names use ext_slug as is. Do not mix Japanese labels or comments into diagrams (hard to read). The correspondence between page keys and Japanese names,topics_group_id is shown in the table directly below the diagram, and each page is linked from that table
  • Even without explicit relation items, restore the relationships between definitions. Common code items (request_no etc.) are not uncommonly linked in designs. In this case, draw with dashed lines (}o..o{) and clearly state outside the diagram that it is "inferred from matching item names" (solid line = confirmed by relation item, dashed line = inferred)
  • Write choices as "key: label". If only the label is written, the key cannot be restored when reflecting in round-trip operation, requiring a question (status の draft: 下書き the key side of is the value that appears in the API)
  • The use of diagrams is described later inMermaid usage. For syntax types and pitfalls, references/mermaid-patterns.md is authoritative
  • All inter-page links are relative paths (contents/tg12_product.md、../api.md). The PDF conversion script converts them to in-page anchors
  • Distinguish facts from speculation. State as definitive what can be confirmed from settings, and for things that depend on operation ("probably used for ~"), clearly state that it is speculation or do not write it

Saving machine-readable definition files

Markdown tables are for humans to read, andas they are, they do not serve as input for reproduction, migration, or diffs(types are translated into Japanese, choices and repetitions are summarized). Also save the read definitions themselves to schema/ .

What to save Acquisition Save destination
API's OpenAPI definition api-export_openapi（api_id Required.api-list once per api_id obtained with ) schema/openapi/api{api_id}_{api名}.json
Content definition topics_group-get(per definition) schema/contents/{ページキー}.json

  • The format is json（api-export_openapi default).openapi_data Write out only the contents of with indentation. Only when the user asks for yaml format:"yaml"(returned as a string)

  • Saving is not a substitute for writing pages. Do not omit the item table, ER diagram, or endpoint list just because raw exists. The moment you omit them, it is no longer a readable specification

  • Do not process. Do not reorder keys, translate types, or delete keys that appear unnecessary (custom_css / search_template_* etc.). Being the original is its only value; summarizing is the job of the Markdown side. Since you are only writing out already-fetched responses, there is no additional read cost

  • Only secret information is masked by the same standard as Markdown(5 in Step 5). Replace the value of the relevant key with "***" and write the masked key name in the corresponding page or a note in the README.Do not silently delete

  • For anything that could not be fetched,Do not create a file. Write "Unconfirmed (reason)" on the corresponding page. If you place an empty file or a partial file, it will later be used as the original

    • api-export_openapi is not in the connected list (rcms_api bundle that does not include the module), write "Unconfirmed (tool invisible)". It is not evidence that an OpenAPI definition does not exist

  • Write one line on the page that references it. Write it as a code path, not a link（.md relative links other than cannot be followed after PDF conversion). Unify paths as relative from the output destination directory (spec/) — if the number of changes per page level, readers get confused ../ the number of changes and readers get confused

    > 機械可読な定義: `schema/contents/tg7_purchase_requests.json`（`topics_group-get` のレスポンス）

  • Since it is a snapshot at generation time, placing it under Git management allows mechanical diffs in the three-way comparison of round-trip operation (references/apply-changes.md Step A)

  • The zip includes the entire output destination directory (it does not go into the PDF. The PDF combines only .md )

Step 5: Inspection

After generation, before delivery, confirm:

  1. Broken links — whether the relative link target files exist in all .md whether the relatively linked destination file within exists
  2. Mermaid syntax — whether each diagram steps on the pitfalls of references/mermaid-patterns.md (Japanese entity names, unquoted symbols). If converting to PDF, the script verifies by actual rendering
  3. Completeness — whether all definitions, processes, and APIs fetched in Step 3 fall under either a page or an "Unconfirmed" note
  4. Round-trip capability — whether it can withstand requests for reflection. ① All pages have comments and kuroco-spec there are comments and id is the actual value ②tools whether the name of the tool actually called is included ③ whether there are any blank cells in the identifier column of the item table ④ whether the choices are in the "key: label" format ⑤ whether the type remains numeric. If you miss this, even if it can be read as a document, it cannot be reflected
  5. confidential information — whether actual values of tokens, secrets, API keys, personal names, or email addresses are mixed in (if you transcribe the setting values as-is, they get in in the form of email_receive_address や admin_nm ). schema/ definition files are also checked by the same standard—because it is a raw response, it is more prone to contamination than Markdown
  6. machine-readable definition files — for the number of API/content definitions that could be retrieved, schema/ there are files in , and whether they can be parsed as JSON. Is there one line in the referencing page containing the save destination path?
  7. aggregation of duplicates — whether the same unconfirmed items and the same notes appear with identical content on multiple pages. The criterion for splitting is "values per page, judgments and handling once on the aggregation page」:
    • Write on each page: the actual values specific to that page (e.g., the setting names and their values that could not be retrieved in this definition) and a link to the aggregation destination
    • Write once on the aggregation page (the unconfirmed items in README or one related file): why it is unconfirmed, how to confirm it, and the scope of impact
    • If you duplicate the same explanatory text on each page, you will have to fix every page each time there is an update, and discrepancies are inevitable

Step 6: Conversion to PDF + zip (optional)

node scripts/build-pdf.mjs spec/ -o dist/
  • Combine all pages in the order of the README.md table of contents, convert to PDF with 1 page = 1 print page break, and zip it together with the full set of Markdown sources
  • Since the zip compresses the entire output destination directory, schema/ definition files are also included. What goes into the PDF is only .md only
  • Requirements: local execution environment, Chrome/Chromium, network connection (retrieve the renderer from a CDN), and thezip command. It does not work in claude.ai's code execution container, so in that case the scope of this skill is up to Markdown delivery
  • For Mermaid rendering failures, the error is displayed down to "which file and which diagram number."Do not deliver a PDF with errors left in it
  • In an environment without Chrome, --html-only can generate up to a single HTML file (open it in a browser and print manually)

How to use Mermaid properly

The placement is decided not by module name but by "where the actual entity is." If the actual entity of the state transition is a status item, place the diagram on the page of that definition even if the approval flow feature (approvalflow) is unused—"do not draw a diagram because the feature is unused" is wrong.

Whether to draw it is decided by "whether the constituent elements are all present and fixed." For a state transition diagram, both states and transitions:

Degree of fixation Representation
Both states and transitions are fixed from the settings/history definitions stateDiagram-v2 draw
The state list is fixed, but transitions are not in the settings (only status items exist) Do not make a diagram. Make it a list of states plus bullet points on which operations change them how, and write one line stating that transitions cannot be fixed from the settings. Drawing speculative arrows causes the diagram to be read as "confirmed information" more than the body text
Only part of the transitions is fixed Diagram only the fixed parts, do not draw unknown transitions in the diagram, and list them in the body text as "unconfirmed"
Diagram Where to use When to use
flowchart README (overall structure), each page under functions/ The overall picture of frontend ⇄ API ⇄ external integrations. Process flow.Do not use it for linear processing of about 3 steps with no branching(prose is sufficient)
erDiagram contents/_index.md Relationships between definitions. Attributes are only the main items and relation items (the authoritative source for all items is the item table on each page)
sequenceDiagram auth.md, functions pages with external integrations The flow from login to token, interaction with external APIs
stateDiagram-v2 The side that holds the state. If the approval flow feature is used, workflow.md; if implemented on the app side via status items or history definitions, the page for that definition State transitions of draft→application→approval→publication

Do not cram too much into one diagram. If it exceeds the guideline, split it (the criterion is references/mermaid-patterns.md）。

Reflecting from the specification document (round-trip operation)

The generated specification document is designed as a document that can be edited and requested with "make changes according to this specification document" (metadata comments, identifier stability, and the README editing rules are mechanisms for that). When a reflection is requested, references/apply-changes.md follow the protocol. Key points:

  1. Do not treat the specification document snapshot as the current state — Reacquire the current state and compare the three: the edited specification document, the current state, and (if possible) the generation-time state. If changes that occurred on the site side after the specification document was generated (drift) conflict with the edits, do not reflect them and report first
  2. Do not write until you present a difference plan and obtain approval — Row deletions, type changes, and identifier changes are treated as destructive changes and confirmed individually one by one, and before execution take site-backup take site-backup
  3. Writing is outside the scope of this skill — Execution follows the conventions of /kuroco-admin-mcp / /kuroco-content-structure Follow the rules of
  4. After writing one item, read it back and verify — A success response is not proof of saving. If a discrepancy appears, stop there and report it
  5. After reflecting, regenerate and synchronize the changed chapters — If you do not synchronize, a false diff will appear on the next reflection

Edit interpretation rules (line addition = new creation, line deletion = deletion'sproposal, identifier change = do not interpret as rename, confirm; choices are key-based; reference values = ignored) — the full table and the procedure for resolving identifiers to IDs are governed by apply-changes.md.Do not guess for ambiguous edits; ask.

Important rules

Rule Description
Read-only In this skill's generation and diff planning, do not call write-type tools. When entering the reflection execution phase, switch to /kuroco-admin-mcp etc., and obtain pre-execution confirmation again
Use only actual values as evidence Do not fill in settings that could not be obtained with default values and write "design of ~". Write unconfirmed as unconfirmed
Do not write secret information Do not write the actual values of tokens, secrets, or passwords anywhere in the specification (only presence, count, and purpose). The specification is a document premised on being shared and delivered, and becomes a leakage route
Do not obtain personal information What the specification needs is definitions and settings, not actual data of content or members.member-list Do not obtain actual data such as cnt=1 で totalCnt look at only
Identifiers as in the original text ext_slug・static_sysnm, endpoint paths, and group names must not be arbitrarily translated into English or renamed. Since the document is matched against the implementation, if even one character of an identifier differs, its value drops.The exception is the content definition'spage keyonly——Because no definition identifier exists on the Kuroco side, it is assigned on the specification side.tg{topics_group_id}_{名前} Always include the actual ID in the format, and clearly state in the correspondence table that it was assigned
Billing awareness Do not redundantly obtain the same information. However, do not omit chapters or inspection for billing reasons—comprehensiveness takes priority

Error handling

Causes and countermeasures for connection and authentication-related issues (400 / 401 / 403 / tool rejection) are the same as the error handling section in /kuroco-admin-mcp . Handling specific to this skill is as follows.

Symptom Countermeasure
Only the tools of some modules are not visible Possibly insufficient scope. Name the necessary module and /x/all/readonly propose re-registration in.Leave invisible chapters as "unconfirmed" and continue generation
Authentication expires during generation Report up to which chapter has been collected and stop. After reauthorization, resume from uncollected chapters (do not re-collect already collected ones)
There is a definition with no extended items at all formData に ext_slug_1 The following does not appear. Write the item table as a definition containing only the basic items (subject / slug / ymd / contents_type). Do not confuse errors with zero results
The context is likely to become insufficient partway through collection For each definition, proceed with "fetch → write out that page" as one cycle. If you write out results sequentially without accumulating them, you can complete the run regardless of how many definitions remain.If you stop partway, list the untouched definition names under "Unverified items" in the README
The PDF conversion script reports a Mermaid error The relevant file and diagram number are displayed.references/mermaid-patterns.md Fix the diagram in light of this, then re-run.--force Ignore and do not output

Temporary workarounds

Issues expected to be resolved by a fix on the Kuroco sideare isolated here. Do not mix them with the permanent procedures (each section above) ——if you mix them, the workaround will remain as a procedure even after it is fixed.Once the resolution condition is met, delete it from this section.

topics_group-get The response exceeds the tool's output limit

  • Symptoms: For definitions with many items, formData と latestRow the double return of plus the Smarty template exceeds 600KB, and the response body is not returned but is saved to a file
  • Workaround: Do not read the saved file in its entirety.formData From ext_slug_N / type_N / limits_N / ext_group_loop_N / ext_parent_slug_N / options_N write a script that extracts only this and puts it into the item table (options_N may have thousands of options, so cut it down to the count and the first few items). The tool's warning text is appended to the end of the saved file, so for the JSON, extract only the leading object and parse it
  • Avoid it in the first place: field-mapping.md For definitions that do not need the four items topics-describe suffice
  • Resolution condition: topics_group-get No longer needed once the response body is returned without being saved.You can tell by trying itso if saving no longer occurs, delete this item

Security notes

  • The specification document is itself a listing of the site's internal structure, sohandle it with awareness of its viewing scope. Follow the user's instructions for the output destination and sharing destination, and do not place it in a public location on your own
  • For static access tokens and external service API keys,write only their existence and purpose(e.g., "holds an incoming webhook for Slack notifications as a site secret"). Do not write the actual values or the last few digits
  • Do not reproduce the full source code of custom processing in the specification document. Summarize it into the processing overview, triggers, and external integration destinations (the Kuroco admin screen is authoritative for the full text)
  • The generation itself is recorded in the admin operation log. In a shared environment, recommend to the user that they inform the team before carrying it out

Anti-patterns

Commonly done Problem Recommended
Finish by just lining up the setting values in a table The setting dump is covered by looking at the admin screen, and the spec document has no value Restore the intent in business language, and list the setting values alongside as evidence
Annotate the ER diagram with Japanese names and comments The diagram becomes unreadable The diagram contains only identifiers. Place the mapping table directly below the diagram
Combine all pages into a single file and output it Too long to read, and diffs cannot be reviewed A split structure is the default. Only the PDF is in combined form
Add a flowchart to a linear 3-step process The diagram becomes noise, and it also lowers the value of the diagrams that are truly needed Make it a diagram only when there are branches, concurrency, or external integrations
Silently omit chapters that could not be retrieved Readers are told that 'that feature does not exist' Explicitly state 'unconfirmed' and the reason
Start writing only after retrieving all definitions Just a few large definitions exhaust the context, and definitions in the latter half are dropped Proceed with 'retrieve -> write out page' for each definition
type_N the numeric value of (35）や ext_option_N the raw string of (draft::default::下書き) pasted into the table as-is Readers cannot read it, and it becomes inferior to the setting dump Translate into type names, and format choices as 'key: label'
Do not leave the source (the tool that was called) The origin of the setting values cannot be traced and cannot be reviewed. At rollout time, the path to re-fetch the current state is also unknown In the metadata comment's tools and the source line, leave the name of the tool actually called
List general tool names as guesses in the source Tool visibility depends on the connection scope, and tool names that were not called become lies Only what was actually called. Write what could not be called on the 'unconfirmed' side
Write the page key as if it were an identifier in the actual settings / use a key with only a name that does not include an ID Readers try to match it against the implementation but cannot find it. In round-trip operation, a key change is mistaken for a rename request tg{topics_group_id}_{名前} Number in the format, and clearly state in the mapping table header that the name part is a convenience key within the spec document
Write guessed usage in an assertive tone It becomes the same 'document diverging from reality' as a hand-written spec Assert only what can be determined from the settings
OpenAPI・topics_group-get Discard the raw response of The table is a summary, so it cannot serve as input for migration, reproduction, or mechanical diffs schema/openapi/ と schema/contents/ Save the original in
Since the definition files are attached, omit the item table and endpoint list It ceases to be a human-readable specification. If you're going to have JSON read, there's no point in creating a specification. Output both. The summary is Markdown, the original is schema/
Deliver with Mermaid errors left in Figures become blank or error strings, and trust in the entire document drops Deliver only after passing the verification in Step 5 / Step 6

Coordination with other skills

Skill Proper use
/kuroco-admin-mcp Prerequisites of this skill (connection, authentication, tool discovery). Correction of settings found in the specification, andRound-trip operationWrite execution is carried out here after obtaining approval
/kuroco-security-audit The same read-only type, but with a different purpose. Specification = description of structure, audit = risk determination. It is good to run them in parallel before delivery.
/kuroco-app-builder Workflow for new construction. If you use this skill to create delivery documentation after construction is complete, a specification based on the actual configuration is produced as is.
/kuroco-content-structure Design decisions when you want to change the structure visualized in the specification, and creation of content definitions
/kuroco-docs Official documentation for each configuration item. When adding source URLs to the specification