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

Hands-on lab — Day 305: Configuring Agents: Memory, Skills, and Rules

Commands

Setup

pip install -r requirements/requirements.txt

Run

python examples/agent_config_engine.py

Test

bash tests/run_tests.sh

File tree

examples/agent_config_engine.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/run-output.txt
expected-output/starter-run.txt
expected-output/test-output.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/agent_config_engine.py
tests/run_tests.sh
tests/test_agent_config.py
troubleshooting.md

Lab README

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

Lesson

Purpose

Build an Agent Configuration & Custom Skill Engine in Python that parses AGENTS.md repository rules, discovers modular skill packages, extracts YAML frontmatter, and performs intent matching for lazy loading.

Learning objectives

  • Parse repository-level AGENTS.md instructions.
  • Discover modular skills and extract YAML frontmatter metadata.
  • Match user intent against skill triggers for lazy loading.
  • Read and bundle skill instructions on demand.

Prerequisites

  • Python 3.10+ installed
  • pytest installed
  • pyyaml installed

Supported operating systems

  • macOS, Linux, Windows WSL2

Hardware requirements

  • Standard CPU, 512MB RAM

Required software

  • Python 3.10+, pytest, pyyaml

Free and open-source options

  • Python Standard Library, Pytest, PyYAML

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt

File structure

  • starter/agent_config_engine.py: Starter implementation skeleton
  • examples/agent_config_engine.py: Verified reference implementation
  • tests/test_agent_config.py: Test suite
  • expected-output/: Captured execution logs

How to run

python3 examples/agent_config_engine.py

What the commands do

  • Loads AGENTS.md rules, scans skill directories, matches triggers, and lazy-loads skill content.

Expected output

Project Rules Status: No AGENTS.md found in workspace root.

Validation steps

Run test runner:

bash tests/run_tests.sh

Tests

The test suite validates:

  • AGENTS.md reading and fallback for missing files
  • Skill directory scanning and YAML frontmatter extraction
  • Intent matching across single and multiple trigger keywords
  • Lazy skill content retrieval

Cleanup

rm -rf .pytest_cache __pycache__ .venv

Troubleshooting

Verify YAML frontmatter in SKILL.md is valid YAML.

Security notes

Runs completely offline on local CPU.

Extension exercises

Implement persistent JSON memory recording.

Day number: 305 of 365

Expected output

FIELDS.md

# Measured Values
- `rules_loaded`: 1
- `skills_discovered`: 1

examples-run.txt

Project Rules Status: No AGENTS.md found in workspace root.

measured-values.txt

rules_loaded=1
skills_discovered=1

run-output.txt

Project Rules Status: No AGENTS.md found in workspace root.

starter-run.txt

An untouched starter fails the suite. Captured from a real run:

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

self = <examples.agent_config_engine.AgentConfigEngine object at 0x10958e190>
user_intent = 'Write a CSS animation'

    def match_skill(self, user_intent: str) -> Optional[Dict[str, Any]]:
>       raise NotImplementedError('TASK 4: implement match_skill.')
E       NotImplementedError: TASK 4: implement match_skill.

examples/agent_config_engine.py:29: NotImplementedError
=========================== short test summary info ============================
FAILED tests/test_agent_config.py::test_load_project_rules_exists - NotImplem...
FAILED tests/test_agent_config.py::test_load_project_rules_missing - NotImple...
FAILED tests/test_agent_config.py::test_discover_and_match_skills - NotImplem...
FAILED tests/test_agent_config.py::test_match_skill_no_match - NotImplemented...
============================== 4 failed in 0.03s ===============================

Implement each TASK in starter/, copy it over examples/, and the same
suite goes green.

test-output.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-305-configuring-agents-memory-skills-and-rules
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 4 items

tests/test_agent_config.py::test_load_project_rules_exists PASSED        [ 25%]
tests/test_agent_config.py::test_load_project_rules_missing PASSED       [ 50%]
tests/test_agent_config.py::test_discover_and_match_skills PASSED        [ 75%]
tests/test_agent_config.py::test_match_skill_no_match PASSED             [100%]

============================== 4 passed in 0.01s ===============================

test-run.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-305-configuring-agents-memory-skills-and-rules
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 4 items

tests/test_agent_config.py::test_load_project_rules_exists PASSED        [ 25%]
tests/test_agent_config.py::test_load_project_rules_missing PASSED       [ 50%]
tests/test_agent_config.py::test_discover_and_match_skills PASSED        [ 75%]
tests/test_agent_config.py::test_match_skill_no_match PASSED             [100%]

============================== 4 passed in 0.01s ===============================

Source files

examples/agent_config_engine.py (3228 bytes)
import os
import re
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:
        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 _parse_simple_yaml(self, text: str) -> Dict[str, Any]:
        data: Dict[str, Any] = {}
        current_list_key = None
        for line in text.splitlines():
            line_str = line.strip()
            if not line_str or line_str.startswith("#"):
                continue
            if line_str.startswith("- ") and current_list_key:
                data[current_list_key].append(line_str[2:].strip())
            elif ":" in line_str:
                parts = line_str.split(":", 1)
                k = parts[0].strip()
                v = parts[1].strip()
                if not v:
                    data[k] = []
                    current_list_key = k
                else:
                    data[k] = v
                    current_list_key = None
        return data
        
    def discover_skills(self) -> List[Dict[str, Any]]:
        catalog = []
        if not os.path.exists(self.skills_dir):
            return catalog
            
        for skill_name in sorted(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()
                match = re.search(r'^---\s*\n(.*?)\n---', content, re.DOTALL)
                if match:
                    try:
                        meta = self._parse_simple_yaml(match.group(1))
                        if isinstance(meta, dict) and "name" in meta:
                            meta["skill_path"] = skill_path
                            catalog.append(meta)
                    except Exception:
                        pass
        return catalog
        
    def match_skill(self, user_intent: str) -> Optional[Dict[str, Any]]:
        catalog = self.discover_skills()
        user_intent_lower = user_intent.lower()
        for skill in catalog:
            triggers = skill.get("triggers", [])
            if isinstance(triggers, list):
                for trigger in triggers:
                    if trigger.lower() in user_intent_lower:
                        return skill
            elif isinstance(triggers, str):
                if triggers.lower() in user_intent_lower:
                    return skill
        return None
        
    def read_skill_content(self, skill_path: str) -> str:
        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()[:60])
metadata.yml (406 bytes)
lesson_id: D305
day: 305
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/agent_config_engine.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (28 bytes)
pytest>=7.0.0
pyyaml>=6.0.0
starter/agent_config_engine.py (1427 bytes)
"""STARTER -- implement each TASK below, then run the tests.

Every function that raises NotImplementedError is yours to write. The
imports, constants and data structures are given; the logic is not.
Run `bash tests/run_tests.sh` to see which tasks are still outstanding.
"""

import os
import re
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:
        raise NotImplementedError('TASK 1: implement load_project_rules.')

    def _parse_simple_yaml(self, text: str) -> Dict[str, Any]:
        raise NotImplementedError('TASK 2: implement _parse_simple_yaml.')

    def discover_skills(self) -> List[Dict[str, Any]]:
        raise NotImplementedError('TASK 3: implement discover_skills.')

    def match_skill(self, user_intent: str) -> Optional[Dict[str, Any]]:
        raise NotImplementedError('TASK 4: implement match_skill.')

    def read_skill_content(self, skill_path: str) -> str:
        raise NotImplementedError('TASK 5: implement read_skill_content.')
if __name__ == '__main__':
    engine = AgentConfigEngine('.')
    print('Project Rules Status:', engine.load_project_rules()[:60])
tests/run_tests.sh (253 bytes)
#!/usr/bin/env bash
set -e
export PYTHONPATH=examples:.
if [ -n "$PYTEST" ]; then
    $PYTEST tests/test_*.py -v
elif command -v pytest &> /dev/null; then
    pytest tests/test_*.py -v
else
    python3 -m unittest discover -s tests -p 'test_*.py' -v
fi
tests/test_agent_config.py (2062 bytes)
import pytest
import tempfile
import os
from examples.agent_config_engine import AgentConfigEngine

def test_load_project_rules_exists():
    with tempfile.TemporaryDirectory() as tmpdir:
        agents_file = os.path.join(tmpdir, "AGENTS.md")
        with open(agents_file, "w", encoding="utf-8") as f:
            f.write("# Project Rules\nUse pytest and ruff.")
            
        engine = AgentConfigEngine(tmpdir)
        rules = engine.load_project_rules()
        assert "# Project Rules" in rules
        assert "Use pytest and ruff." in rules

def test_load_project_rules_missing():
    with tempfile.TemporaryDirectory() as tmpdir:
        engine = AgentConfigEngine(tmpdir)
        rules = engine.load_project_rules()
        assert "No AGENTS.md found" in rules

def test_discover_and_match_skills():
    with tempfile.TemporaryDirectory() as tmpdir:
        skill_dir = os.path.join(tmpdir, ".agents", "skills", "db_migrate")
        os.makedirs(skill_dir, exist_ok=True)
        
        skill_file = os.path.join(skill_dir, "SKILL.md")
        with open(skill_file, "w", encoding="utf-8") as f:
            f.write("""---
name: db_migrate
description: Database migration assistant
triggers:
  - migrate
  - database migration
---
# Migration Instructions
Run alembic upgrade head.
""")
            
        engine = AgentConfigEngine(tmpdir)
        catalog = engine.discover_skills()
        assert len(catalog) == 1
        assert catalog[0]["name"] == "db_migrate"
        assert "migrate" in catalog[0]["triggers"]
        
        matched = engine.match_skill("Please perform a database migration on users")
        assert matched is not None
        assert matched["name"] == "db_migrate"
        
        content = engine.read_skill_content(matched["skill_path"])
        assert "Run alembic upgrade head." in content

def test_match_skill_no_match():
    with tempfile.TemporaryDirectory() as tmpdir:
        engine = AgentConfigEngine(tmpdir)
        matched = engine.match_skill("Write a CSS animation")
        assert matched is None

Troubleshooting

Troubleshooting - Day 305

Ensure skill directory paths follow .agents/skills/<name>/SKILL.md.

Security notes

Security - Day 305

Validate and sanitize skill frontmatter and helper scripts.