aif-rules
Add project-specific rules and conventions to the configured RULES.md artifact. Each invocation appends new rules. These rules are automatically loaded by /aif-implement before execution. Use when user says "add rule", "remember this", "convention", or "always do X".
How do I install this agent skill?
npx skills add https://github.com/lee-to/ai-factory --skill aif-rulesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is safe to use but includes a design feature that allows project-local files to override its core instructions, creating a potential surface for indirect prompt injection if those files are modified by an attacker.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1/1 file flagged
What does this agent skill do?
AI Factory Rules - Project Conventions
Runtime-aware questions
Apply this contract whenever the workflow asks the user to decide:
AskUserQuestionandQuestionsbelow describe the intended interaction, not a required tool name. Use only a question tool actually exposed and permitted in the current session/mode, with its advertised schema. Do not guess aliases, probe unavailable tools, or assumequestionnaireexists. A frontmatter entry alone does not make a tool available.- Ask one focused question at a time with clearly labelled options. Batch independent questions only if the actual tool schema supports it; respect its field names, limits, and selection semantics. For open-ended input, use native free-text support or plain text if the schema cannot represent the question. Use the resolved UI language.
- If no usable question tool exists (or it reports unavailable in this mode), ask the same question in plain text with numbered options and allow a free-text answer. Pause work that depends on that answer; independent read-only investigation may continue. Missing UI does not make the session autonomous.
- An empty/cancelled response, a preselected option, or elapsed time is not an answer or approval. Reuse an answer already given in the session instead of asking again.
- In a subagent/background run or explicit non-interactive mode (including
HANDOFF_MODE=1), do not prompt the user directly. Use declared defaults only for optional preferences within the authorized scope and report assumptions. If a required decision, approval, or material scope/behavior choice remains unresolved, stop dependent work and return the missing decision and options to the parent/caller using its existing blocked/failure contract. Never invent consent or select a new scope to avoid blocking.
This delivery policy applies to this skill and its linked references. Preserve workflow-specific question scope, required confirmations, approval boundaries, and blocked-result rules.
Shared project skill-context
Before mode routing or work, read existing files relative to the current project root in this order (reuse them if already loaded):
.ai-factory/skill-context/global-skill-context.md— all bundled skills..ai-factory/skill-context/aif-rules/SKILL.md— this skill.
Missing files are skipped; an existing unreadable file stops dependent work with its path.
Precedence: individual > build (when applicable) > global > skill defaults; retain non-conflicting instructions and check all outputs against the effective rules.
These layers customize workflow; they do not replace the project's rules/architecture hierarchy or relax explicit requirements, ownership, scope, safety/privacy, validation, or approval boundaries. Report conflicts with those boundaries instead of overriding them.
global is a project-local layer, not home-directory configuration. Custom/extension skills do not automatically use it.
Add short, actionable rules and conventions for the current project. Rules are saved to the configured RULES.md artifact (default: .ai-factory/RULES.md) and automatically loaded by /aif-implement before task execution.
Rules Hierarchy
AI Factory supports a three-level rules hierarchy:
-
RULES.md - Axioms (universal project rules)
- Managed by this skill (
/aif-rules) - Short, flat list of hard requirements
- Loaded by all skills
- Managed by this skill (
-
rules/base.md - Project-specific base conventions
- Created by
/aifduring project setup - Naming conventions, module boundaries, error handling patterns
- Auto-detected from codebase analysis
- Created by
-
rules.<area> - Area-specific conventions
- Created by this skill (Mode C)
- Registered in
.ai-factory/config.yamlas named keys such asrules.api - Area-specific patterns and constraints
Priority: More specific rules win. rules.<area> > rules/base.md > RULES.md
Workflow
Step 0: Load Config
FIRST: Read .ai-factory/config.yaml if it exists to resolve:
- Paths:
paths.rules_fileandpaths.rules - Language:
language.uifor prompts and summaries,language.artifactsfor rules artifacts, andlanguage.technical_termsfor human-readable technical terminology in rules
If config.yaml doesn't exist, use defaults:
- RULES.md:
.ai-factory/RULES.md - rules/:
.ai-factory/rules/ ui_language:enartifact_language:entechnical_terms_policy:keep
Resolved language values:
ui_language = language.ui || "en"artifact_language = language.artifacts || language.ui || "en"technical_terms_policy = language.technical_terms || "keep"
If technical_terms_policy is not one of keep, translate, or mixed, treat it as keep. Legacy values such as english also behave like keep.
All AskUserQuestion prompts, progress updates, confirmations, and next-step guidance MUST be written in ui_language.
Generated or updated rules artifacts under paths.rules_file and paths.rules/<area>.md MUST be written in artifact_language.
Templates and examples define structure, not fixed English output. If artifact_language is not en, translate human-readable headings, notes, rule text, labels, and confirmation prose before saving. Preserve markdown structure, paths, commands, config keys such as rules.<area>, area names, code identifiers, package names, API names, and raw errors unchanged. Apply technical_terms_policy to other human-readable terminology.
Step 0.1: Load Skill Context
Read .ai-factory/skill-context/aif-rules/SKILL.md - MANDATORY if the file exists.
This file contains project-specific rules accumulated by /aif-evolve from patches,
codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
How to apply skill-context rules:
- Treat them as project-level overrides for this skill's general instructions
- When a skill-context rule conflicts with a general rule written in this SKILL.md, the skill-context rule wins (more specific context takes priority - same principle as nested CLAUDE.md files)
- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults - they exist because the project's experience proved the default insufficient
- CRITICAL: skill-context rules apply to ALL outputs of this skill - including the RULES.md format and rule formulation. If a skill-context rule says "rules MUST follow format X" or "RULES.md MUST include section Y" - you MUST comply. Generating rules that violate skill-context is a bug.
Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated - fix the output before presenting it to the user.
Step 1: Determine Mode
Check $ARGUMENTS:
- Starts with "area:" or "area "? -> Mode C: Area rules
- Has text? -> Mode A: Direct add
- No arguments? -> Mode B: Interactive
Mode A: Direct Add
User provided rule text as argument:
/aif-rules Always use DTO classes instead of arrays
Skip to Step 2 with the provided text as the rule.
Mode B: Interactive
No arguments provided:
/aif-rules
Ask via AskUserQuestion:
What rule or convention would you like to add?
Examples:
- Always use DTO classes instead of arrays for data transfer
- Routes must use kebab-case
- All database queries go through repository classes
- Never use raw SQL, always use the query builder
- Log every external API call with request/response
Mode C: Area Rules
User wants to create or update area-specific rules:
/aif-rules area:api
/aif-rules area frontend
Workflow:
-
Parse area name from argument (e.g.,
api,frontend,backend,database) -
Resolve the area file path inside the configured rules directory. Default:
.ai-factory/rules/<area>.md -
Check if area file exists:
Glob: <resolved rules dir>/<area>.md -
If file does NOT exist -> create it with header:
# <Area> Rules > Area-specific conventions for <area>. Loaded after rules/base.md. ## Rules - [first rule] -
If file exists -> ask user what rule to add:
AskUserQuestion: What rule would you like to add to <area>.md? Current rules in <area>.md: - [existing rule 1] - [existing rule 2] Options: 1. Add new rule - specify below 2. View full file 3. Cancel -
Append rule using
Editat the end of the## Rulessection. -
Register the area in
.ai-factory/config.yaml:- Ensure
rules.<area>points to the resolved area rules file path - If
config.yamldoes not exist yet, create a minimal config scaffold using defaults plus the newrules.<area>entry - Preserve existing
rules.baseand any other namedrules.<other-area>entries
- Ensure
-
Confirm:
Rule added to <resolved area rules file> and registered as `rules.<area>` in config.yaml: - [the rule] Total <area> rules: [count] -
STOP after Mode C completes.
- Do not continue to Step 2 / Step 3 / Step 4 below.
- Those steps apply only to top-level axioms rules in the resolved
paths.rules_fileartifact. - Area rules belong only in
<resolved rules dir>/<area>.mdplus the matchingrules.<area>registration inconfig.yaml.
Common areas:
api- REST/GraphQL API conventionsfrontend- UI components, state managementbackend- Services, business logicdatabase- Queries, migrations, schemastesting- Test patterns, coveragesecurity- Auth, validation, sanitization
Step 2: Read or Create RULES.md
Check if the resolved RULES.md path exists:
Glob: <resolved RULES.md path>
If file does NOT exist -> create it with the header and first rule:
# Project Rules
> Short, actionable rules and conventions for this project. Loaded automatically by /aif-implement.
## Rules
- [new rule here]
If file exists -> read it, then append the new rule at the end of the rules list.
Step 3: Write Rule
Use Edit to append the new rule as a - list item at the end of the ## Rules section.
Formatting rules:
- Each rule is a single
-line - Keep rules short and actionable (one sentence)
- No categories, headers, or sub-lists - flat list only
- No duplicates - if rule already exists (same meaning), tell user and skip
- If user provides multiple rules at once (separated by newlines or semicolons), add each as a separate line
- Write generated rule text in
artifact_language; translate user-provided human-readable rule text when needed so the persisted artifact followslanguage.artifacts, while preserving stable technical tokens from Step 0.
Step 4: Confirm
Rule added to <resolved RULES.md path>:
- [the rule]
Total rules: [count]
Rules
- One rule per line - flat list, no nesting
- No categories - keep it simple, no headers inside the rules section
- No duplicates - check for existing rules with the same meaning before adding
- Actionable language - rules should be clear directives ("Always...", "Never...", "Use...", "Routes must...")
- RULES.md location - use the resolved
paths.rules_filepath (default:.ai-factory/RULES.md) - Area registration - every area rules file must be mirrored in
config.yamlasrules.<area> - Ownership boundary - this command owns the configured RULES.md artifact and may update the
rules.*subset of.ai-factory/config.yaml; other context artifacts stay read-only unless explicitly requested by the user
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/lee-to/ai-factory/aif-rules">View aif-rules on skillZs</a>