setup-agent-skills

Setup Agent Skills

Deploy the project knowledge infrastructure for the target repository. This Skill is the sole installation and upgrade entry point. Project runtime depends on the AGENTS.md / CLAUDE.md marker block and docs/agents/project-knowledge.mjs; hosts without Hooks execute according to the marker block, and the project Hooks of Codex / Claude Code then inject the same protocol.maintain returns the confirmation process and the two deployed format documents;protocol returns the body of the marker block.

1. Explore the project

First read and preserve the true state of the target project:

• Root AGENTS.md、CLAUDE.md and the existing project knowledge sections in it;
• docs/CONTEXT.md、docs/CONTEXT-MAP.md, the Context files declared by the map, and docs/rules/；
• docs/agents/ existing documents under it and project-knowledge.mjs；
• the current host's project configuration: Codex uses .codex/hooks.json or .codex/config.toml, Claude Code uses .claude/settings.json；
• the Git status before this run. Existing user changes must not be overwritten, staged, or committed.

When starting from a subdirectory or an independent sub-repository, search upward for an existing Context entry; if the outer CONTEXT-MAP.md clearly links the current Context, use the project where the map resides as the domain document root. When there is no existing layout, use the current project Git root.

Select Codex or Claude Code according to the host currently executing the Skill, do not guess based on which instruction files exist in the project, and do not modify the other host's configuration along the way.

2. Determine the layout and changes

• An existing and valid single/multiple Context layout remains unchanged.
• When neither entry point exists: if the repository has only one primary business boundary or multiple independent boundaries cannot be confirmed, use docs/CONTEXT.md; if there are indeed multiple business Contexts that can be described independently, use docs/CONTEXT-MAP.md。
• When both entry points exist, or when different choices would significantly change knowledge ownership, ask for confirmation.

First determine whether this deployment uses a single Context or multiple Contexts, then form a clear change list:

• Create or update the two format documents and project-knowledge.mjs；
• Context descriptionthat need to be supplemented or corrected, and Map links that need to be standardized.description directly use the existing Map link text, Context title, or the project's existing service name as the discovery list display name; do not move long business responsibilities into that field.
• RULE file names and references are organized according to the current scenario format. Scenario codes are ordered by importance; each scenario is renumbered consecutively from 01 , and sequence numbers within a scenario are likewise ordered by importance; synchronize all inbound references within the same candidate change. Complete the Frontmatter for every RULE; when there is no direct reference use references: [], and change existing references to relative paths according to the directory where the declaring file resides.
• When the body contains multiple independently judgeable constraints or a multi-section RULE, compress, rearrange, or split it: first record the original constraints item by item, keep each split-out file as an atomic constraint, and preserve relationships through references ; the semantics must not be omitted before and after migration.
• The three Hooks that the current host needs to add or update.

When the scenario can be clearly determined from the file name and existing rule content, organize directly; when there are multiple reasonable results for scenario division or project customization, present suggestions and then ask the user.

3. Protect project customization

The files built into this Skill are release seeds, not a reason to overwrite user content:

• When the current file is consistent with a known old official template, it can be upgraded to the current seed;
• When the file contains project terminology, custom processes, or other obvious customization, retain the content, show the current file and the suggested result, and merge only the parts confirmed by the user;
• Agent instructions only maintain the project-knowledge marker block;
• Hook only maintains the three project-level entries that invoke docs/agents/project-knowledge.mjs hook ;
• When ownership cannot be reliably identified, stop writing to that file and notify the user, without affecting other read-only checks.

Do not read or modify user-level, local-level, managed-level, or plugin-level Hooks.

4. Generate and validate the candidate snapshot

In a temporary directory, copy the knowledge files involved in this change, first generate the complete candidate result, and do not directly modify the real project:

1. Generate two format documents according to the determined layout, and deploy scripts/project-knowledge.mjs. The following command must be run to generate the documents; do not directly copy the source seed that introduces both layouts at the same time into the project:

   node <setup-agent-skills目录>/scripts/render-layout-docs.mjs <single|multiple> <候选根>/docs/agents
   

   The generated context-format.md may contain only the selected layout;rules-format.md is shared by both layouts.

2. Retain the Context body, shared concepts, and Relationships; compress, split, and consecutively renumber RULEs according to the change list, and synchronize all inbound references, checking item by item that every original constraint still has a corresponding location; at the same time, recursively check all reference targets to confirm that missing, out-of-range, and cyclic references can all be explicitly handled by the validator.

3. Run at the candidate root:

   node docs/agents/project-knowledge.mjs validate-context
   node docs/agents/project-knowledge.mjs validate-rules
   node docs/agents/project-knowledge.mjs scope
   node docs/agents/project-knowledge.mjs maintain
   node docs/agents/project-knowledge.mjs protocol
   

4. Check scope.rule_scene_options sorted by sceneId , with each item containing only sceneId、sceneName、rules, where rules is sorted by ruleId and each item contains only ruleId、ruleName; from the returned results, select representative RULEs to execute --context without load, and for a multi-Context layout, select a representative Context to verify loading with --context . When the project has no RULE, validate only the fixed Context document.maintain returns the two formats for the confirmation process and the current layout, so there is no need to read these files again.protocol returns the marker block body, which is written as-is into the marker block in Section 7.

When Node is unavailable or candidate validation fails, provide the direct error and the failed command, delete the temporary snapshot, and leave the real project unchanged.

5. Deploy the knowledge files

After the candidate snapshot passes, show the files that will be created, updated, renamed, and deleted. When project customization, RULE renaming, or deletion is involved, obtain user confirmation before side effects occur.

Create recovery copies only for the real files that will be modified in this round, then apply the already-validated candidate knowledge tree:

• context-format.md → docs/agents/context-format.md
• rules-format.md → docs/agents/rules-format.md
• scripts/project-knowledge.mjs → docs/agents/project-knowledge.mjs

If any step fails, restore the files already modified in this round, and report what still requires manual handling.

6. Install the current host Hook

All three events invoke the same project-internal entry point:UserPromptSubmit、SessionStart(only matches compact）、SubagentStart. According to the current host, merge the corresponding template into the project configuration; the fields and event structure are based on the template, and do not copy the template content again:

• Codex：hook-templates/codex-hooks.json
• Claude Code：hook-templates/claude-settings.json

Codex

• When the project already has .codex/hooks.json , parse the JSON and merge or update only its own three Hooks.
• When the project uses only .codex/config.toml inline Hooks, maintain the # project-knowledge:start / # project-knowledge:end marker section at the end of the file, and write the three Hooks from the template equivalently into the section; when a complete marker section already exists, update the content within the section in place, and do not parse or rewrite the TOML outside the marker section.
• When both Codex Hook representations exist at the same time, only update the one that already contains its own Hook; when not yet installed, write to .codex/hooks.jsonfirst, and remind the user that Codex will merge the two sources at the same level.
• The Hook command locates docs/agents/project-knowledge.mjsfrom the current project's Git root, and does not use the absolute path at install time as its identity.
• Other Hooks and configurations remain unchanged; when similar entries are found whose ownership cannot be confirmed, remind the user and do not delete them automatically.

Claude Code

• .claude/settings.json is created when it does not exist; when it exists, only merge its own three matcher groups and handlers from the template.
• The handler uses the template's command + args, without going through the shell.
• On repeated runs, update in place its own Hook with the same event, same matcher, and same project script parameters.
• Other settings, matcher groups, and Hooks retain their original semantics and order; when JSON is corrupted, stop writing to that file and remind the user.

After installation, check that each event in the current project configuration has only one own Hook. Trust is only a reminder: if it can actually be triggered in the current host, verify the three events; if it cannot be automatically confirmed, truthfully report "Hook pending trust", and do not maintain an extra state file.

The Hook output for all three events must not inline scope, the Context list, or the RULE path; only inject the deferred selection protocol. The first sentence is based on the hook output, and the rest of the body is the same as the steps in protocol .

The additionalContextLimit in the template is only responsible for truncation protection, and does not replace Hook copy conciseness.

7. Switch Agent instructions

In the root AGENTS.md、CLAUDE.md , maintain the following unique marker block; when both files exist, update both, but the Hook is still only installed on the current host. The body inside the block must equal the complete output of node docs/agents/project-knowledge.mjs protocol :

<!-- project-knowledge:start -->
## 项目知识

<protocol 输出>
<!-- project-knowledge:end -->

• Existing complete marker block: only replace the text inside the block.
• Existing project-customized project knowledge paragraphs outside the marker block: show the retained content and the proposed result, and merge after user confirmation.
• No marker block: append once at the end of the file.

8. Completion check

• Both format documents and project-knowledge.mjs have been deployed;
• single/multiple Context, Map, RULE scenarios, and cross-directory recursive references pass the corresponding validator;
• scenario codes and in-scenario sequence numbers are arranged by importance, and each scenario is numbered consecutively from 01 ; each RULE has Frontmatter, a non-empty body, and expresses only one atomic constraint that can be judged independently; Context description is the discovery list display name;
• the current host has exactly one of each of the three project Hooks, and other configurations have not been overwritten;
• each Agent instruction file has one complete marker block, and the body equals the protocol output, and does not depend on the Hook to load;
• when triggered from the project root and from a subdirectory, the Hook only provides the deferred selection protocol;scope the Context returned bysceneId , ruleId , and loadare sufficient to constructmaintain returns the confirmation process and the current layout format;
• the deployed context-format.md only describes the currently selected single-Context or multiple-Context layout;
• running this Skill a second time consecutively does not produce duplicate blocks, duplicate Hooks, or meaningless file changes;
• the user's original changes and project customizations have been retained.

Finally report the layout, files created or updated, RULE count, numbering and body check,scope Structured discovery and compact loading evidence, cross-directory recursive loading evidence, idempotent results from repeated runs, current host Hook verification results, as well as conflicts or trust reminders that still require user handling.