Skip to content

Own rules, skills and roles

The project always overrides the template. You never edit anything under .act/; a guard (template-write-guard) refuses writes there. Everything that is yours goes into docs/ai/ and docs/project/, and survives every update.

docs/ai/rules.md lists the rule files the assistant loads, each import followed by its rules as checkboxes:

@../../.act/rules/shared/20-code.md
- [x] `R-code-language`
- [ ] `R-code-encoding`
  • Switch a rule off: remove its cross. The file is still loaded whole, but an unchecked rule counts as off. If a template update moves a rule to another rule file, act-update moves its checkbox line along in an edited docs/ai/rules.md, mark and reason unchanged, so a rule you switched off stays off. If you do not import the new file, the move is only reported; rules.py also reports a moved rule whose new file you shadow with your own copy under docs/ai/local/rules/ that lacks it (the rule does not load), and an ID listed twice in one block (only the last line counts).
  • New template rules: act-update and the session start also enter rules the template added into an edited docs/ai/rules.md, as a checkbox line per rule, and a new rule file as an import block at the end of its section. Your own text, unchecked boxes and imports you removed stay as they are, and a removed line does not come back (.act-lock.json records what was offered); its rule still counts as on, so remove the cross to switch it off. What cannot be entered safely is named by python .act/scripts/rules.py --add-missing.
  • Switch a whole area off: delete its @ import line.
  • Trim the template per project: the keys profile (minimal, standard or full, the default) and exclude in the Scope section of docs/ai/config.md leave out template skills, roles, rule files (not shared/10-safety.md) and topics. The session start removes the copies, switches the import line of an excluded rule file to a bare path in docs/ai/rules.md and names the cut in one line; it takes effect from the next session, and the checks stay on. See Scope.
  • Replace a rule’s wording: under ## Overrides, add a bullet of the form - replaces `R-...`: <your version> naming the rule and your version (lines starting with <!-- are skipped). A replaces line wins over the template text whether the rule is checked or not.
  • Add your own rules: under ## Own rules, one item per rule that has no counterpart in the template. An indented list directly below an own rule (or a replaces line) belongs to it and is read as part of its text. Keep each own rule to one line: incident, evidence and identifiers belong in the project docs, which are not loaded in every session. The “Own rules” section of the coding_rules.md scaffold has a table of where each kind of rule belongs (an own rule, a path-bound rule file under .claude/rules/, a rule set of its own, the project docs, or nowhere). act-doctor warns when the “Own rules” sections of docs/ai/rules.md and docs/project/coding_rules.md together pass own-rules-budget (default 6000 characters, off or 0 switches it off) and names up to five lines that read like history; it never blocks. See Checks.

The orchestrator rule files imported in the section “Orchestrator only” of docs/ai/rules.md (.act/rules/orchestrator/, or their overrides under docs/ai/local/rules/orchestrator/) do not reach workers; other text in that section does. The template’s roles load no CLAUDE.md, and a hook hands them the shared rules, the coding rules, your own rules from docs/ai/rules.md, CLAUDE.local.md and ~/.claude/CLAUDE.md instead, without .act/rules/orchestrator/. A rule meant for workers therefore belongs in the shared or coding sections or under ## Own rules. python .act/scripts/rules.py --worker shows what a worker gets.

Keep the marks (<!-- act:overrides -->, <!-- act:own-rules -->) where they are; the mechanism finds the sections through them. python .act/scripts/rules.py --imports shows what is actually loaded. Each file ends with its size in characters (a CRLF line end counts as one), and a last line gives the total, split into the template’s share under .act/ and the project’s. Coding rule sets work the same way in docs/project/coding_rules.md; a set line takes an optional reason after the path (- [ ] use: <path> — <reason>), like a group line, to record why a set is off; a set of your own, or a local override of a template set, goes to docs/ai/local/coding/<set>.md and is switched on in docs/project/coding_rules.md too (only the local file is loaded, instead of the template one). act-update lists new template sets and groups in docs/project/coding_rules.md: a new set unchecked, a new group of a checked set checked; your lines, boxes and reasons stay. update.py --plan previews exactly that list, writing nothing. While docs/project/coding_rules.md has changes that are not committed, the update enters nothing (they would go into the update commit) and says so with the command to run after your commit: python .act/scripts/rules.py --add-new-coding. rules.py --list and --validate also show Claude Code’s path-bound rules under .claude/rules/ with their paths: patterns, warn about a pattern that matches no file, and note a file without paths: (it loads at every start); such a rule loads only once a matching file is read or written, and act-adopt offers to keep these files as they are. The rule IDs are in the rules reference and the coding rules reference.

docs/ai/local/ mirrors .act/: a file with the same relative path wins over the template version. docs/ai/local/<path> is looked up before .act/<path>. To change a template skill file, copy it to docs/ai/local/skills/<name>/<file> and edit the copy; the project copy is then generated from your override. You own the folder, and the assistant writes there only when you tell it to.

If the template renames or removes a file you override, the override silently has no effect; act-doctor reports such a file with the most similar name under .act/. Rule overrides, roles and your own skills are left out, and so is an own script or coding set unless one name is the start of the other or differs only in its extension.

The text the assistant writes has formats of its own: a file docs/project/formats/<name>.md (commit.md, changelog.md, release-notes.md, project-readme.md) replaces the template’s format for that subject completely; the keys that pick a preset are in Formats.

Optional working methods (test-first, spec-first, simple-changes) are rule sets switched on by the methods row in the Scope section of docs/ai/config.md. They are written into docs/project/coding_rules.md as imports, so the orchestrator and every worker load them, and a group can be unchecked there like in any rule set. A method of your own goes to docs/ai/local/methods/<name>.md. See Scope.

The folder also holds optional files of your own, for example reminders.md (one “remind me” line per row, with an optional cadence) and security-accepted.md (see The security check).

A skill is a directory with a SKILL.md that starts with YAML frontmatter (name, description) and contains tool-neutral instructions. Put your own at docs/ai/local/skills/<name>/SKILL.md; its tool copies (.claude/skills/<name>/, and .agents/skills/<name>/ only when codex, copilot, gemini or cursor is configured) are written by act-load-settings on import. A hand-placed skill gets them at the next session start (with session-start-refresh at its default block) or update.py run, or by python .act/scripts/unit_copies.py. A copy follows its source: an unedited copy is refreshed at the session start when the source changes, and act-doctor flags a copy you edited by hand, which is kept; change the source in docs/ai/local/skills/, not the copy. One you deleted stays deleted. Until then the skill is reachable via /act <name>. A skill name that the template already ships is an override of that skill, not a new one; act-doctor reports it until you keep it with python .act/scripts/doctor.py --accept skill:<name> or delete it (own-rules-review). Write the description trigger-first (“Use when …”, 15 to 55 words, no list of steps), because it is all an agent sees before loading the skill; python .act/scripts/skills.py --check lints it, and doctor reports a missing or overlong description in your own skills. doctor also checks the frontmatter of your own skills and roles: valid YAML, a name equal to the folder or file name, no unknown or invalid fields. A long skill keeps the core flow in SKILL.md and puts detail in references/<topic>.md, loaded only when needed. The shipped skills are listed in the skills reference.

An own role is a file docs/ai/local/agents/<name>.md with its rules. A new role is its own bridge source and needs frontmatter (name, description, tier/reasoning, tools); only an override of a template role is plain text without frontmatter. Tier and reasoning (of a skill: reasoning in its frontmatter, overridable by a row with the skill’s name) can also be set in the Roles table of docs/ai/config.md (see Tiers and reasoning); the tool-specific file under .claude/agents/ is created by init and update; an own role also gets it at session start under the default session-start-refresh. Once such a file exists, its text is yours: updates only refresh its model and effort lines. The template’s roles carry omitClaudeMd: true; an own role without the field loads CLAUDE.md as before, including the orchestrator rules, so add the field if you want it to get only the worker rules (see Update). The built-in roles are described in Roles.

A package is a second way to bring rules, coding sets, skills, roles, topics, scripts and checks into a project without editing .act/; nothing is installed without the plan, the diff and your yes in the chat. Finding, installing, updating, removing, writing and submitting a package: see the Packages guide. The load order of the rules is in Layers.

Two skills carry your deviations from the template to another project.

Both skills start only as typed slash commands (/act-export-settings, /act-load-settings); a request in plain words does not start them.

act-export-settings writes what you changed against the template into one settings.md: your own rules, switched-off rules and groups, replaces overrides. Nothing about the project itself (name, work state) goes in. Options:

  • --all also lists the unchanged rules.
  • --with-scripts, --with-checklists, --with-agents, --with-skills add the files from docs/ai/local/; any of them produces a .zip instead of a .md.
  • --with-topics adds the topic rules under docs/ai/local/rules/topics/: a topic of your own as [+] <name>.md, an override of a template topic as [~] <name>.md with a fingerprint of the template topic it overrides. Whole files, so it also produces a .zip.
  • --with-formats adds your format files from docs/project/formats/ (only the four names above), so it produces a .zip; act-load-settings writes them back there.
  • --strict aborts instead of substituting a placeholder; use it when the file leaves your own hands.
  • --out PATH chooses the location; the default is .act-local/export/. --profile writes to your personal profile instead. A path outside the project is refused by the outside-root check: keep the default folder, add the path to outside-root-allow (Checks), or set ACT_OUTSIDE_ROOT=warn for one run.

The script scans every value for credentials, mail addresses, IP addresses, local paths and internal hosts and replaces a hit with a visible <setup:KIND> placeholder. It reports the finding count; skim the file before sending it anywhere.

act-load-settings imports such a file. python .act/scripts/settings_load.py plan shows what would happen and writes nothing; with no file named, it takes everything in .act-local/import/. A file outside the project is refused by outside-root: put it into .act-local/import/, allow its folder in outside-root-allow, or set ACT_OUTSIDE_ROOT=warn for one run. apply then writes what is clear. Overlaps with your own rules are judged, not applied silently, and anything unresolved lands in one inbox entry. Bundled scripts, skills and roles are shown to you before they are written, and a skill or role that shares a name with a template one, or asks for risky frontmatter (hooks, MCP servers, permission modes), is reported and never written. Own topic rules and topic overrides go to docs/ai/local/rules/topics/<name>.md: a topic already there with different content is reported as changed and left alone; an override whose template topic no longer exists is reported as dead and not written; one whose template topic changed since the export is reported as changed-since-export, to review by hand. When the question “Write ?” for a settings file gets no input (no terminal after all), the file is not written.