Creating Augment Agent Rules

This skill provides comprehensive guidance on creating rules for Augment Agent. Rules are different from skills - they define general coding guidelines and standards that are always applied or content-based.

When to Use This Skill

• Creating coding standards and guidelines
• Defining workflow requirements (like PR workflows)
• Establishing best practices for the codebase
• Setting up always-applied rules for Augment Agent
• Creating Augment-specific functionality rules

Rules vs Skills

Use Rules When:

• ✅ General coding guidelines apply to all code
• ✅ Content-based or always-applied standards
• ✅ Augment-specific functionality
• ✅ Workflow enforcement (e.g., PR requirements)
• ✅ Code style and formatting standards
• ✅ Security or compliance requirements

Use Skills When:

• ✅ Specialized domain knowledge is needed
• ✅ Metadata-based discovery is important
• ✅ Content should be loaded on-demand
• ✅ Following agentskills.io standard
• ✅ Task-specific instructions

Rule Structure

A rule is a Markdown file in the rules/ directory with optional YAML frontmatter:

rules/
├── pr-workflow.md
├── code-style.md
└── security-guidelines.md

Step-by-Step Workflow

1. Choose a Rule Name

The rule filename should:

• Use kebab-case (lowercase with hyphens)
• Be descriptive and clear
• End with .md
• Reflect the rule's purpose

Good examples: pr-workflow.md, code-style.md, security-guidelines.md Bad examples: Rule1.md, my_rule.md, WORKFLOW.md

2. Determine Rule Type

Rules can have different types in the frontmatter:

type: auto

Automatically applied to all interactions. Use for critical, always-enforced rules.

---
type: auto
---

Use for:

• Workflow requirements (PR workflows)
• Security standards
• Critical best practices
• Code quality gates

No frontmatter (content-based)

Applied based on content relevance. Augment loads these when the content is relevant to the task.

Use for:

• Language-specific guidelines
• Framework-specific patterns
• Domain-specific standards
• Optional best practices

3. Create the Rule File

Following the PR workflow rule, create a feature branch first:

git checkout -b add-rule-name

Then create the rule file:

# Create in rules/ directory
touch rules/rule-name.md

4. Write the Rule Content

Structure Your Rule

A well-structured rule should include:

1. Title - Clear heading describing the rule
2. Purpose - Why this rule exists
3. Requirements - What must be done
4. Guidelines - How to follow the rule
5. Examples - Good and bad examples
6. Exceptions - When the rule doesn't apply
7. Enforcement - How the rule is enforced

Example Rule Template

---
type: auto
---

# [Rule Name]

**[Brief statement of the rule's core requirement]**

## Purpose

[Explain why this rule exists and what problem it solves]

## Requirements

[List specific requirements that must be followed]

1. Requirement 1
2. Requirement 2
3. Requirement 3

## Guidelines

[Provide detailed guidance on how to follow the rule]

### Step 1: [Action]
[Details]

### Step 2: [Action]
[Details]

## Examples

### Good Example

[Show correct implementation]

### Bad Example

[Show incorrect implementation]

## Exceptions

[List any exceptions to the rule]

- Exception 1
- Exception 2

## Enforcement

[Explain how the rule is enforced]

5. Use Clear, Actionable Language

Good:

• ✅ "NEVER push directly to main"
• ✅ "ALWAYS create a feature branch"
• ✅ "Use conventional commit format"

Bad:

• ❌ "Try to avoid pushing to main"
• ❌ "Consider using branches"
• ❌ "Commits should probably follow a format"

6. Include Visual Markers

Use emojis and symbols to make rules scannable:

• ✅ Correct/Required
• ❌ Incorrect/Forbidden
• ⚠️ Warning/Caution
• 📋 Note/Information
• 🔒 Security-related
• 🚀 Performance-related

7. Provide Context and Rationale

Explain WHY the rule exists, not just WHAT it requires. This helps developers understand and follow the rule.

Good:

## Why This Rule Exists

Pushing directly to main bypasses code review, CI/CD checks, and can introduce
bugs into production. PRs ensure all changes are reviewed and tested.

Bad:

## Rule

Don't push to main.

Common Rule Types

Workflow Rules

• PR requirements
• Branch naming conventions
• Commit message formats
• Code review processes

Code Quality Rules

• Linting standards
• Testing requirements
• Documentation requirements
• Code style guidelines

Security Rules

• Authentication requirements
• Data handling standards
• Dependency management
• Secret management

Architecture Rules

• Design patterns
• File organization
• Module structure
• API design standards

Best Practices

1. Be Specific: Vague rules are hard to follow
2. Be Consistent: Rules should align with each other
3. Be Practical: Rules should be enforceable
4. Provide Examples: Show both good and bad examples
5. Explain Why: Include rationale for the rule
6. Keep Updated: Review and update rules regularly
7. Make Scannable: Use headings, lists, and markers
8. Test the Rule: Ensure Augment can understand and apply it

Complete Example

See rules/pr-workflow.md in this repository for a complete example of a well-structured rule with:

• Clear frontmatter (type: auto)
• Strong enforcement language
• Step-by-step workflow
• Examples of what to do and what not to do
• Branch naming conventions
• Exception handling
• Rationale for the rule

Validation

After creating a rule:

1. Test with Augment: Ask Augment to perform a task that should trigger the rule
2. Verify Enforcement: Ensure the rule is being followed
3. Check Clarity: Make sure the rule is understandable
4. Review Examples: Confirm examples are accurate
5. Sync to Augment: Ensure rule is in ~/.augment/rules/

Syncing Rules

Rules in the rules/ directory are automatically synced to ~/.augment/rules/ via:

./sync-to-augment.sh

This happens automatically on commit via the git post-commit hook.

Next Steps

After creating your rule:

1. Follow the PR workflow (as defined in rules/pr-workflow.md)
2. Create a feature branch
3. Add the rule file
4. Commit with conventional commit message
5. Push the feature branch
6. Create a PR with auto-merge
7. Wait for merge
8. Pull main and sync

Remember: Rules define how we work. Make them clear, actionable, and valuable.