install-rules

Skill: Install Rules

Purpose

Install therulesfrom a rule source (passive constraints on AI behavior) into the editor's rule targets. The primary source is the project's "rules/" directory, or a user-specified Git repository. Supported installation targets: Cursor (.cursor/rules/) and Trae IDE (.trae/project_rules.md / .trae/user_rules.md)。

---

Core Objective

Primary Objective: Install rules from a source repository into Cursor or Trae IDE through explicit user confirmation and conflict detection.

Success Criteria(all requirements must be met):

1. ✅ Source resolved: Read the rule source (this repository's "rules/" or the specified Git repository), and build the rule list from "INDEX.md" or the directory listing
2. ✅ Analyze target: Scan existing target files and identify conflicts/duplicates before any writes
3. ✅ Show installation plan: Show an explicit plan for each rule action ("create/skip/conflict/update") and show the target path to the user
4. ✅ User confirmation: The user explicitly approves the plan before any files are created or modified
5. ✅ Rules installed: The selected rules are written to the target destination in the correct format (Cursor ".mdc" files or Trae managed blocks)
6. ✅ Report output: The post-installation summary includes the actions performed, target paths, and any conversion notes or failures

AcceptanceTest: Can the user verify which rules were installed, where they were installed, and whether any conflicts were detected?

---

Scope Boundaries (Scope Boundaries)

This skill is responsible for：

• Resolving the rule source (this repository or a Git repository)
• Listing the rules available in the source
• Analyzing the target state (existing files/conflicts)
• Building and presenting the installation plan
• Installing rules into Cursor (.mdc format) or Trae (managed blocks)
• Reporting the installation results

This skill is not responsible for：

• Discovering which skills are available (use "discover-skills")
• Creating or writing new rules (out of scope)
• Modifying rule content (preserve source content accurately)
• Installing skills (rules only)

Handoff point: Once the rules are installed and reported, the skill is complete. If the user wants to discover skills, hand off to "discover-skills".

---

Use Cases (Use Cases)

• This project: Install all or selected rules from the current repository's rules/ into the current project's Cursor or Trae rules.
• Another Git repository: The user provides owner/repo (and optionally a branch/ref and subpath); list the rules in that repository and install the selected rules into Cursor or Trae.
• Bootstrap: After cloning ai-cortex or another repository that provides rules, install its rules so the agent respects them in the user's workspace.

---

Behavior (Behavior)

1. Resolve source：

   • This project: Use the repository's rules/ directory. Treat rules/INDEX.md as the authoritative list; if present, parse the registry to get rule names and file paths. Otherwise list rules/ all *.md files (excluding INDEX.md）。
   • the specified Git repository: the user provides "owner/repository" or a full clone URL, plus an optional branch/ref and subpath (e.g., "rules" or "docs/rules"). Discover rules by: (a) looking for "INDEX.md" (or equivalent) in the subpath and parsing the registry, or (b) listing the "*.md" files in that directory. If the repo or path does not exist or contains no rules, report this explicitly and do not write files.

2. List rules: output a list of installable rules (name, short description, or scope). Have the user select "all" or a subset by name.

3. Analyze target state (required)：

   • Cursor: list the existing./.cursor/rules/*.mdc(project-level) or user-level rules directory (if selected). Determine which target filenames already exist.
   • Trae: read the selected target file (./.trae/project_rules.md or ./.trae/user_rules.md, or the global user level (if selected)) (if it exists). Detect whether a managed block already exists (see step 6).

4. Formulate an installation plan (required)：

   • For each selected rule, decide on an action: "create", "skip (identical)", "conflict (different)", or "update (explicit overwrite approved)".
   • The default must be conservative:
     • An existing but different target is a "conflict" until the user explicitly approves overwriting.
     • An existing and identical target is "skip".
   • Output the plan before any writes, including the intended target paths and per-rule actions.

5. Confirm before writing：

   • Do not create, modify, or overwrite before the user explicitly confirms the plan.cursor/rules/、.trae/or any file under any target path.
   • If overwrites are included, explicit confirmation is required listing which rule targets will be overwritten.

6. Install to Cursor：

   • Target path: the project level is./.cursor/rules/(relative to the repo root); the user level depends on the platform (e.g., "~/.cursor/rules/", if applicable). Prefer the project level unless the user requests the user level. If the directory does not exist, create it.
   • Format: write each rule to a ".mdc" file. Map the source rule metadata to front-matter ("description", optional "globs", optional "alwaysApply"), and preserve the rule body.
   • Idempotency: before writing, normalize the content and compare it with the existing target content (if any). If identical, "skip".
   • Conflicts: if the target exists and is different, do not overwrite unless the plan includes "update" and the user explicitly confirms the overwrite.

7. Install to Trae (managed block)：

   • Target path: the project level is./.trae/project_rules.md; the user level is "./.trae/user_rules.md" (project scope) or the global user-level path (if Trae supports it). Prefer the project level unless the user requests the user level. If the.trae/directory does not exist, create it.
   • Managed block (required)：
     • Write only within the managed block to avoid modifying user-written rules.
     • Use markers such as "" and "" around the managed block.
     • If the managed block exists, replace the entire block content; if not, insert the block (usually appended to the end of the file).
   • Block content：
     • Within the block, use the "## Rule: " header to present one section per rule in a stable order (prefer the "rules/INDEX.md" registry order if available).
     • Preserve each rule body (everything after the source header content).
     • Deduplicate by rule name within the managed block (one name → one section).
   • Idempotency: if the re-rendered managed block is identical to the current managed block, "skip" and do not rewrite the file.

8. Output: after installation, report the plan, actions performed, target paths, and any conversion notes or failures.

---

Input & Output

Input

• Source: default "this project" (the current repository "rules/"). Alternatively: Git repository owner/repo or URL, with optional branch/ref and subpath (e.g. rules、docs/rules）。
• Target: one of Cursor, Trae, or both.
• Scope: "All" rules or a subset (list of rule names).
• Destination: project-level or user-level; default project-level.
• Conflict policy: default is conservative (do not overwrite); overwriting requires explicit confirmation.

Output

• Before installation: rule list + target analysis summary + installation plan with target paths (创建/跳过/冲突/更新）。
• After installation: actions performed, target paths, and any errors or conversion notes.

---

Limits

Hard Boundaries

• Do not write without confirmation: without explicit user confirmation of the plan, do not create or modify files under .cursor/rules/、.trae/ or any target path.
• Do not overwrite without confirmation: if the target already exists and differs, do not overwrite unless the user explicitly agrees and the plan includes an "update" for that target.

Skill Boundaries (avoid overlap)

Do not do these (other skills can handle them)：

• Discovery skill → 发现技能
• Create or edit rule content → out of scope
• Installation techniques (SKILL.md) → out of scope

---

Self-Check

Core success criteria (all criteria must be met)

• Source resolved: rule source read and rule list built from "INDEX.md" or directory listing
• Target analyzed: scan existing target files and identify conflicts/duplicates before any writes
• Installation plan provided: plan with per-rule actions and target paths shown to the user
• User confirmation: the user explicitly approves the plan before creating or modifying any files
• Rules installed: selected rules written to the target destination in the correct format
• Reported output: The post-install summary includes the actions performed, target paths, and any transformation notes or failures

---

Examples (Examples)

Example 1: Install all rules in this project to Cursor

• Read rules/INDEX.md and build the rule list.
• Analyze .cursor/rules/ and formulate a conservative plan.
• Present the plan, get confirmation, perform the "create"/"update" operations, then report.

Example 2: Install rules from another Git repository to Trae

• Parseowner/repoand the subpath.
• Discover rules, build a plan for the Trae managed block, confirm, then write the managed block.
• Report the installed rules and target file paths.

---

Appendix: Output Contract (Appendix: Output Contract)

After this skill finishes running, it must generate a post-install summary report (Side-effect report) in the following format, so that the agent or subsequent steps can parse the installed rules and whether there are skips/conflicts:

Field	Type	Description
rule_name	String	Name of the rule installed or processed
action	String	Action performed (created | skipped | conflict | updated)
target_path	String	Target path where the rule is written (e.g. .cursor/rules/xxx.mdc or .trae/project_rules.md)
status	String	Final status (success | failed | pending_confirmation)

---

Appendix: Output Contract (Appendix: Output Contract)

After this skill finishes running, it must generate a post-install summary report (Side-effect report) in the following format, so that the agent chain can parse the installed rules and whether there are skips/conflicts:

Field	Type	Description
rule_name	String	Name of the rule installed or processed
action	String	Action performed (created | skipped | conflict | updated)
target_path	String	Target path where the rule is written (e.g. .cursor/rules/xxx.mdc)
status	String	Final status (success | failed | pending_confirmation)