AI Engineering: Agents and Applications › AI Coding Agents › Day 305

Day 305: Configuring Agents: Memory, Skills, and Rules

Day 305 of 365 — Configuring Agents: Memory, Skills, and Rules

Configure persistent repository knowledge for AI coding agents: implement AGENTS.md, hierarchical rule engines, custom executable skills, and persistent architectural memory to eliminate repetitive prompt onboarding.

Course
AI Engineering: Agents and Applications
Category
AI Coding Agents
Reading time
≈ 35 min
Practical time
≈ 50 min
Lesson duration
1h 25m
Last verified
2026-08-30

Hands-on lab for this lesson

Lab files on GitHub: https://github.com/ai-roadmap-365/ai-roadmap-365.github.io/tree/main/labs/sections/ai-engineering/day-305-configuring-agents-memory-skills-and-rules

  1. Get the hands-on files. Clone the labs repository once (you can reuse this clone for every lesson). This works on macOS, Linux, and Windows (PowerShell or WSL):
    git clone https://github.com/ai-roadmap-365/ai-roadmap-365.github.io.git
    cd ai-roadmap-365.github.io
  2. Open this lesson's lab. Move into the directory for this specific day. Every lab lives at the same predictable path — section / subsection / week / day:
    cd labs/sections/ai-engineering/day-305-configuring-agents-memory-skills-and-rules
  3. Read the lab guide. Open `README.md` in that directory. It lists the exact commands, what each does, the expected output, and how to check your work — read it before running anything.
  4. Run it and check your work. Follow the README's "How to run" section: run the example first to see the finished result, then complete the numbered exercises in `starter/`, then run the tests. The tests pass (exit 0) only when your work is correct.
    bash tests/run_tests.sh   # or the test command named in the lab README

You can also open the lab as a local page (works offline, shows the file tree and expected output).

Learning objectives

By the end of this lesson you will be able to:

Prerequisites

Why this matters

When working across multiple repositories and enterprise applications, manually repeating the same setup instructions to your AI coding agent in every prompt (“We use Poetry for package management, run tests with pytest, format with ruff, use async SQLAlchemy sessions, and never touch the legacy auth module”) is exhausting and error-prone. If an engineer forgets to state a constraint, the agent defaults to generic assumptions, producing code that violates internal architectural invariants.

Modern coding environments solve this via Persistent Configuration Subsystems:

  1. Repository Rules (AGENTS.md, .cursorrules, CLAUDE.md): Automatically injecting repository build instructions, code style standards, and architectural invariants into every agent turn.
  2. Modular Custom Skills (.agents/skills/): Reusable domain playbooks equipped with YAML frontmatter, helper automation scripts, and reference documentation that are lazy-loaded on demand.
  3. Persistent Repository Memory: A structured knowledge store capturing architectural decisions, historical post-mortems, and tricky edge-case workarounds so the agent learns from previous mistakes.

Mastering agent configuration architecture enables engineering teams to codify decades of institutional knowledge directly into the agent’s runtime environment.

Hierarchical Agent Configuration Architecture showing Global Rules, Project AGENTS.md, Custom Skills On-Demand, Persistent Memory Store, and Task Prompt

The idea in plain language

Diagram: onboarding a contractor with and without written standards

Diagram: the three persistent configuration subsystems of a coding agent

Think of configuring an AI coding agent like onboarding a contractor into an engineering organization:

The contractor becomes instantly productive on minute one with zero repetitive human onboarding.

Historical background

Diagram: the progression from editor dotfiles to the AGENTS.md standard

Agent configuration systems evolved through three distinct standardizations:

1. In-Repo Configuration Standards (.editorconfig, .eslintrc)

Software engineering has long utilized in-repo dotfiles to enforce editor formatting and linting rules across distributed teams. AGENTS.md represents the AI equivalent of .editorconfig.

2. The Rise of .cursorrules and System Prompts (2023)

The IDE community introduced .cursorrules to allow developers to supply custom system prompts on a per-workspace basis.

3. The AGENTS.md Open Standard and Skill Systems (2024–Present)

The AI ecosystem converged on standardized, multi-agent configuration standards (AGENTS.md), combining hierarchical rule resolution, tool MCP bridges, and directory-based skill architectures.

What it is — and what it is not

Let us define the core components of agent configuration:

What Agent Configuration Is:

What Agent Configuration Is Not:

+-------------------------------------------------------------------------------+
|                       CONFIGURATION SYSTEM TAXONOMY                           |
+-------------------+-----------------------+-------------------+---------------+
| Layer             | Primary Artifact      | Scope             | Loading Mode  |
+-------------------+-----------------------+-------------------+---------------+
| Global Settings   | `~/.config/rules`     | All Workspaces    | Always Active |
| Project Standards | `./AGENTS.md`         | This Repository   | Always Active |
| Custom Skills     | `.agents/skills/*/`   | Specific Domain   | Lazy-Loaded   |
| Persistent Memory | `.agents/memory.json` | Project History   | Indexed Match |
| Task Spec Prompt  | Current Turn Message  | Single Session    | Immediate     |
+-------------------+-----------------------+-------------------+---------------+

Why it was created and what problems it solves

Agent configuration subsystems solve four critical enterprise development challenges:

1. Eliminating Prompt Repetition

Developers never have to re-type build commands, test flags, or style guidelines in individual chat messages.

2. Enforcing Architectural Invariants

Rules guarantee that all generated code adheres to strict internal conventions (e.g. “Always use Pydantic V2 models with snake_case fields”).

3. Preventing Token Bloat with Lazy Skills

Rather than stuffing 500 pages of AWS deployment documentation into every prompt, skills expose short trigger descriptions and load full manuals only when triggered.

4. Institutional Knowledge Preservation

When a developer solves a tricky concurrency bug, they can record the solution in repo memory so the agent never reintroduces the bug in future features.

How it works

Diagram: the four problems that persistent agent configuration solves

Let us inspect the complete lifecycle of a modular Agent Skill:

[1. Skill Packaging]
  - Directory: `.agents/skills/db-migrate/`
  - Contains: `SKILL.md`, `scripts/schema_diff.py`, `references/alembic.md`
  - Frontmatter:
      name: db-migrate
      description: "Use when creating or modifying database migration scripts."
                         │
                         ▼
[2. Agent Scans Skill Catalog at Startup]
  - Registers skill metadata (50 tokens)
                         │
                         ▼
[3. User Submits Prompt: "Add status column to users table"]
                         │
                         ▼
[4. Intent Matcher Triggers 'db-migrate' Skill]
  - Agent loads `SKILL.md` via `view_file` tool (Lazy Load)
                         │
                         ▼
[5. Agent Follows Skill Playbook & Executes Helper Script]
  - Runs: `python3 .agents/skills/db-migrate/scripts/schema_diff.py`
  - Applies generated migration file
  - Runs `pytest tests/test_migrations.py`

Agent Skill Directory Structure and Lifecycle showing SKILL.md Frontmatter, Trigger Match, Lazy Load, Helper Script Execution, and Context Return

An everyday analogy

Diagram: avionics systems as an analogy for agent configuration layers

Think of configuring an AI coding agent like programming a modern avionics flight computer:

Examples in practice

Let us build a complete Python Agent Configuration & Rules Engine that parses AGENTS.md, resolves hierarchical rules, and lazy-loads modular skills:

import os
import re
import yaml
from typing import Dict, Any, List, Optional

class AgentConfigEngine:
    def __init__(self, workspace_root: str):
        self.workspace_root = os.path.realpath(workspace_root)
        self.skills_dir = os.path.join(self.workspace_root, ".agents", "skills")
        self.agents_md_path = os.path.join(self.workspace_root, "AGENTS.md")
        
    def load_project_rules(self) -> str:
        '''Load repository-level AGENTS.md instructions if present.'''
        if os.path.exists(self.agents_md_path):
            with open(self.agents_md_path, "r", encoding="utf-8") as f:
                return f.read().strip()
        return "No AGENTS.md found in workspace root."
        
    def discover_skills(self) -> List[Dict[str, Any]]:
        '''Scan skills directory and extract YAML frontmatter metadata.'''
        catalog = []
        if not os.path.exists(self.skills_dir):
            return catalog
            
        for skill_name in os.listdir(self.skills_dir):
            skill_path = os.path.join(self.skills_dir, skill_name, "SKILL.md")
            if os.path.exists(skill_path):
                with open(skill_path, "r", encoding="utf-8") as f:
                    content = f.read()
                # Extract YAML frontmatter between --- blocks
                match = re.search(r'^---\s*
(.*?)
---', content, re.DOTALL)
                if match:
                    try:
                        meta = yaml.safe_load(match.group(1))
                        meta["skill_path"] = skill_path
                        catalog.append(meta)
                    except Exception:
                        pass
        return catalog
        
    def match_skill(self, user_intent: str) -> Optional[Dict[str, Any]]:
        '''Find the most relevant skill based on user query keywords.'''
        catalog = self.discover_skills()
        user_intent_lower = user_intent.lower()
        for skill in catalog:
            triggers = skill.get("triggers", [])
            for trigger in triggers:
                if trigger.lower() in user_intent_lower:
                    return skill
        return None
        
    def read_skill_content(self, skill_path: str) -> str:
        '''Lazy-load full skill instructions when triggered.'''
        with open(skill_path, "r", encoding="utf-8") as f:
            return f.read()

if __name__ == "__main__":
    engine = AgentConfigEngine(".")
    print("Project Rules Status:", engine.load_project_rules()[:100])

Implications: security, privacy, performance, scalability, and cost

1. Security Risks of Untrusted Skill Helper Scripts

Custom skills often contain executable bash/python scripts in scripts/. Never install untrusted third-party skills from the internet without inspecting the script code for malicious commands or data exfiltration.

2. Context Budget Management with Lazy Loading

If an organization has 50 custom skills (averaging 1,000 tokens each), loading all skills upfront consumes 50,000 tokens per turn. Exposing only the 50-token catalog and lazy-loading skills keeps base prompt overhead under 1,500 tokens.

Deep Dive: Enterprise Rule Hierarchy and Namespace Resolution

In large engineering organizations with hundreds of microservices, rule management requires a strict precedence hierarchy to avoid conflicting directives:

Diagram: the precedence order for conflicting agent configuration rules

[Global Developer Preferences: ~/.config/rules]
  - "Preferred editor: VS Code, Git commit style: Conventional Commits"
                            │
                            ▼
[Organization-Wide Architecture Standards: Org Policies]
  - "Security: All endpoints require OAuth2 JWT, Database: PostgreSQL only"
                            │
                            ▼
[Repository-Level Standards: ./AGENTS.md]
  - "Build: poetry run pytest, Linters: ruff check, Style: Google Python Style"
                            │
                            ▼
[Modular Custom Skills: .agents/skills/*/SKILL.md]
  - "Skill: Database Migration, Trigger: 'migrate', Helper: scripts/diff.py"
                            │
                            ▼
[Active Task Specification Prompt]
  - "Task: Add stripe_customer_id to users table. Non-goal: Do not touch auth."

When resolving conflicts, the Principle of Specificity applies:

Designing Reusable Custom Skills with Executable Tooling

A world-class Agent Skill is not just static markdown; it is an executable automation bundle:

Diagram: the three components of a well-designed agent skill

Alternatives: free, open source, and commercial

Configuration LayerFile FormatIndustry StandardTooling Support
AGENTS.mdMarkdownOpen StandardCursor, Aider, Claude Code, Cline
.cursorrulesMarkdown / TextCursor ProprietaryCursor IDE
CLAUDE.mdMarkdownAnthropic StandardClaude Code CLI
Skill DirectoriesSKILL.md + ScriptsAntigravity / AgenticModern Agent Platforms
+-----------------------+-----------------------+-----------------------+
| Mechanism             | System Rules          | Modular Skills        |
+-----------------------+-----------------------+-----------------------+
| Scope                 | Universal across repo | Domain-specific task  |
| Loading Behavior      | Always in context     | Lazy-loaded on trigger|
| Executable Tooling    | Static text only      | Bundled helper scripts|
| Size Target           | 200 - 800 tokens      | 1,000 - 4,000 tokens  |
+-----------------------+-----------------------+-----------------------+

When to use it — and when not to

Diagram: when agent rules and skills are worth authoring

Choose AGENTS.md and Custom Skills when:

Do NOT use heavy skill directories for:

Deep Dive: The Anatomy of an Enterprise AGENTS.md File

Let us examine the complete, standardized structure of a production-grade AGENTS.md configuration file for an enterprise microservice:

# Repository Agent Guidelines: Billing & Subscription Service

## 1. Project Overview & Architecture
- Service: Billing and Invoicing Engine
- Tech Stack: Python 3.12, FastAPI, SQLAlchemy (Async), PostgreSQL, Redis, Poetry
- Architectural Pattern: Layered Domain-Driven Design (Models -> Repositories -> Services -> Routes)

## 2. Build, Test, and Quality Commands
- Environment Setup: `poetry install`
- Run Unit Tests: `poetry run pytest tests/unit/ -v`
- Run Integration Tests: `poetry run pytest tests/integration/ --db-reuse`
- Static Type Checking: `poetry run mypy src/ --strict`
- Linting & Formatting: `poetry run ruff check src/ tests/ && poetry run ruff format --check src/`

## 3. Mandatory Architectural Invariants
- All database queries MUST use async SQLAlchemy sessions (`AsyncSession`).
- Never perform blocking I/O (e.g. `requests.get` or `time.sleep`) inside async route handlers; use `httpx.AsyncClient` and `asyncio.sleep`.
- All monetary amounts MUST be represented as integer cents (`amount_cents: int`) or `decimal.Decimal` to prevent floating-point rounding errors.
- Never log raw credit card numbers, CVVs, or unredacted bearer tokens.

## 4. Forbidden Actions & Non-Goals
- DO NOT add external third-party dependencies to `pyproject.toml` without explicit maintainer approval.
- DO NOT modify database migration history files in `alembic/versions/`; always create new forward migration scripts.
- DO NOT disable linter rules or add `# type: ignore` without documenting the exact reason.

When an agent loads this file into its system context, it immediately adopts these architectural constraints, eliminating 99% of common coding errors.

Managing Skill Deprecations and Evolution in Growing Repositories

As codebases evolve over months and years, custom agent skills must be maintained just like production software libraries:

  1. Version Pinning & Changelogs: Include a last_updated and version field in SKILL.md frontmatter so team members know when instructions were last verified against current SDK releases.
  2. Automated Skill Validation: Set up CI jobs that periodically execute skill helper scripts (python3 .agents/skills/*/scripts/test.py) to verify that migration and scaffolding helpers remain compatible with the latest repository dependencies.
  3. Pruning Obsolete Skills: When a legacy framework (e.g. migration from Flask to FastAPI) is retired, delete the corresponding skill directory to prevent agents from loading obsolete architectural patterns.

Diagram: the three practices that keep agent skills accurate over time

Advanced Topic: Dynamic Context Injection and Semantic Skill Routing

In massive enterprise repositories with hundreds of microservices and custom libraries, a static listing of skills can still consume valuable prompt space. Advanced coding environments implement Semantic Skill Routing:

Diagram: how semantic routing selects one skill from a large catalogue

Standard Operating Procedure: Auditing and Versioning AGENTS.md

To prevent configuration decay across distributed engineering teams, maintainers should establish a standard operating procedure for AGENTS.md:

  1. Pull Request Linting: Treat AGENTS.md as code. Run markdown linters and link validators to ensure all file paths and command examples remain valid.
  2. Post-Mortem Action Items: Following any production incident or tricky debugging session, add a specific preventative invariant to AGENTS.md (“Never use raw SQL string interpolation in analytics reporting queries”).
  3. Periodic Review Cadence: Review AGENTS.md at the start of each development sprint to deprecate retired commands and update testing flags.

The AI connection

Knowledge check

  1. What is AGENTS.md? A standardized markdown file placed in a repository root that provides persistent instructions, rules, and commands to AI coding agents.
  2. Why should custom skills be lazy-loaded? To prevent prompt context bloat by loading full documentation only when a user’s task matches the skill’s triggers.
  3. What is the highest priority level in rule resolution? The task-specific prompt authored by the developer for the immediate turn.

Hands-on exercise

In this lab, you will implement an Agent Configuration & Custom Skill Engine in Python. Your implementation will:

  1. Parse and extract instructions from AGENTS.md files.
  2. Discover modular skill packages and extract YAML frontmatter metadata (name, description, triggers).
  3. Implement intent matching to lazy-load skill playbooks dynamically.
  4. Verify configuration loading, skill matching, and error handling across automated pytest tests.

Expected output

============================= test session starts ==============================
collected 5 items

tests/test_agent_config.py .....                                         [100%]

============================== 5 passed in 0.02s ===============================
[CONFIG ENGINE] Loaded AGENTS.md rules (240 tokens).
[SKILL CATALOG] Discovered 2 skills: 'db-migrate', 'api-scaffold'.
[INTENT MATCHER] Matched query 'run database migration' -> 'db-migrate' skill loaded.

Validate your work

Run the pytest test suite:

pytest tests/run_tests.sh

Troubleshooting

  1. YAML frontmatter parsing error: Ensure the YAML header in SKILL.md is enclosed by triple hyphens (---).
  2. Skill trigger mismatch: Check case sensitivity in intent matching logic.

Common mistakes

Practice assignment

Implement a Persistent Memory Store (.agents/memory.json) that allows the agent to record and query historical architectural decisions with semantic tags.

Extension challenge

Build a Rule Conflict Detector that compares AGENTS.md against global user rules and alerts the developer if contradictory instructions are detected (e.g. conflicting linter commands).

Quiz

Q1. What is the primary function of an `AGENTS.md` (or `.cursorrules`, `CLAUDE.md`) file placed in a repository root?

  1. To store binary database backups
  2. To encrypt git commits
  3. To give every agent the project's standing instructions
  4. To run a local web server
Show answer

Answer: C. To give every agent the project's standing instructions

`AGENTS.md` and repository rule files automatically prime coding agents with project-specific context and constraints.

Q2. What is the recommended priority hierarchy when resolving conflicting rules in a coding agent?

  1. Random selection
  2. Default System > Global User > Project rules > Task prompt
  3. Alphabetical order of filenames
  4. Task prompt, project rules, user rules, defaults
Show answer

Answer: D. Task prompt, project rules, user rules, defaults

More specific scopes (task prompt, project rules) take precedence over general global defaults.

Q3. What components constitute an Agent Skill directory?

  1. A SKILL.md file
  2. Only a .jpg image
  3. A compiled binary DLL
  4. A git branch
Show answer

Answer: A. A SKILL.md file

Skills are modular packages containing `SKILL.md` instructions, executable scripts, and reference documentation.

Q4. Why is recording persistent architectural memories (e.g. past post-mortems or tricky gotchas) beneficial for coding agents?

  1. It makes the hard drive fill up much faster
  2. It stops the agent repeating solved mistakes
  3. It disables linter checks
  4. It forces the agent to use C++
Show answer

Answer: B. It stops the agent repeating solved mistakes

Persistent repository memory gives agents institutional knowledge, preventing repeated errors.

Q5. How should dynamic on-demand skills be loaded into an agent's context to prevent token bloat?

  1. Load all 500 skills into every prompt by default
  2. Delete all skills after one use
  3. Show summaries, and load the full file on demand
  4. Compress skills into zip files
Show answer

Answer: C. Show summaries, and load the full file on demand

Lazy-loading skills based on metadata summaries prevents prompt bloat while retaining rich capabilities.

Glossary

AGENTS.md
A standardized markdown file in a repo root specifying instructions, rules, and commands for coding agents.
Hierarchical Rule Engine
A configuration system resolving rule precedence from global user settings down to task prompts.
Agent Skill
A modular directory containing `SKILL.md` instructions, helper scripts, and domain knowledge loaded on-demand.
Persistent Repo Memory
A structured knowledge store recording past architectural decisions, edge cases, and gotchas.
Skill Frontmatter
YAML metadata at the top of a `SKILL.md` file specifying skill name, description, and triggers.
Context Priming
Automatically injecting repository conventions into an agent's initial system prompt.
Architectural Invariant
A strict structural rule (e.g. 'All database calls must use async sessions') enforced on the agent.
Lazy Skill Activation
Reading full skill documentation only when the user's intent matches the skill's trigger description.

Sources and further reading


Kept in this browser, no account needed. Your progress page turns the whole record into one link you can bookmark or open on another device.