add-rule-to-best-practice

Add Rule To Best Practice

This skill is needed for creating and improving rules/*.md inside the target best-practice skill directory.

Do not use it as a general guide to Markdown, to Bitrix code, or to the structure of all project skills. First determine the target directory where the needed skill with SKILL.md and the catalog rules/is located. If the user did not specify the path explicitly and there are several candidates from the context, first clarify the target directory. Do not update SKILL.md, or other skill files inside the target directory, unless the user asked for this separately.

What the skill does

• writes a new rule file for a specific Bitrix entity or layer;
• strengthens an existing rule file to AI-first format;
• maintains a uniform level of quality relative to rules/controller.md и rules/routing.md;
• helps avoid mixing neighboring abstractions in one file.

Required reading

Before creating or rewriting a rule file:

1. Read SKILL.md in the target directory to maintain consistency with the parent skill.
2. Read rule-file-standard.md.
3. For the default structure and wording of examples, read rule-file-example-minimal.md.
4. If the topic is complex, with branching, legacy, or several decision points, additionally read rule-file-example-complex.md.
5. If the target SKILL.md uses a manual router for rule files, read skill-router-entry-example.md.
6. If the target rules/*.md already exists in the target directory, read it in full.
7. Read 1-2 neighboring rules/*.md in the target directory that are closest in layer and responsibility.
8. Gather only the framework context that is needed specifically for this entity.

Workflow

1. Determine the exact entity of the rule file and its boundaries.
2. Separate what should live in this file and what should remain in neighboring rules.
3. Assemble the structure according to the canonical sections from rule-file-standard.md.
4. Choose the form template: rule-file-example-minimal.md by default, rule-file-example-complex.md only for complex topics.
5. First write the rules, then the examples, then the binary checklist.
6. Check whether all independent decision points, edge cases, compatibility paths and exceptions have examples; if not, add more ## Example N, without limiting yourself to two sections.
7. Check how SKILL.md routes rule files in the target directory; if there is an explicit router block of the form "When to read rules/...", add a correct trigger block for the new rule file following the example from skill-router-entry-example.md, so that it becomes discoverable.
8. Remove general reasoning, repetitions and items where several norms are mixed in one bullet.
9. Check that the file helps the agent make decisions in code, rather than turning into a mini-tutorial on all of Bitrix.

Requirements for the result

• Each rule must be operational and lead to a specific decision in code or review.
• When it intersects with another abstraction, explicitly refer to the neighboring rules/*.md.
• Make the examples self-contained and explain which norm they demonstrate.
• For complex topics, the number of ## Example N is not fixed: cover all independent important cases, and do not stop at two examples out of inertia.
• The checklist must work as a self-review in the format да/нет.
• Prefer the reference files of this skill as the source of the standard, rather than random current rule files from the target directory.
• If the target SKILL.md uses a manual router for rule files, the new rules/*.md must get a correct trigger block in this router.

When to stop and clarify

Do not guess and ask the user if:

• the new rule intersects equally strongly with two different abstractions;
• the project convention conflicts with framework best practice and it is unclear which takes precedence here;
• the user actually wants to change the skill-router or the global template, and not only the target rule-file.