Build Your Own AI Agents: Markdown Files Over Generic Frameworks

November 2025 · Masrur Hossain

Every codebase has its own personality. Its own quirks. Its own way of doing things. When you work on a project long enough, you develop an intuition for how to get things done—a mental playbook of steps that work for this particular system.

These playbooks are valuable. They represent hard-won knowledge about what works. And I believe you should codify them—not in a generic automation framework, but in simple markdown files that serve as instructions for AI agents.

The N-Step Process You've Already Discovered

Think about the last significant change you made to your infrastructure or codebase. Maybe you:

• Added a new microservice
• Migrated a database
• Set up monitoring for a new component
• Onboarded a new third-party integration

You probably followed a process. Maybe it was documented somewhere, maybe it lived entirely in your head. But there was a sequence: first you do X, then you check Y, then you create Z, then you verify A, B, and C.

This process is unique to your environment. It accounts for your team's conventions, your CI/CD setup, your monitoring stack, your deployment strategy. It's the product of trial and error, production incidents, and accumulated wisdom.

This is exactly what you should turn into an AI agent.

What Is an AI Agent (Really)?

Strip away the hype, and an AI agent is simple: it's a set of instructions that an AI model follows to accomplish a task. The more specific and contextual those instructions, the better the agent performs.

You don't need a framework. You don't need a platform. You need a markdown file that clearly describes:

1. What the task is
2. What context the AI needs
3. What steps to follow
4. What to verify at each step
5. What the successful outcome looks like

That's it. The AI model provides the intelligence. Your markdown file provides the direction.

An Example: Adding a New Service

Here's what a custom AI agent might look like for adding a new service to a specific codebase:

# Agent: Add New Service

## Context
You are working in a monorepo with the following structure:
- /services - individual service directories
- /infrastructure/terraform - Terraform configs per service
- /k8s - Kubernetes manifests
- /.github/workflows - CI/CD pipelines

## Task
Create a new service with all required infrastructure and deployment configuration.

## Required Information
- Service name (lowercase, hyphenated)
- Service description
- Port number
- Required environment variables
- Database requirements (if any)

## Steps

### 1. Create Service Directory
- Create /services/{service-name}
- Copy template from /services/_template
- Update package.json with service name and description
- Update README.md with service-specific documentation

### 2. Create Terraform Configuration
- Create /infrastructure/terraform/{service-name}
- Include: IAM role, CloudWatch log group, SSM parameters
- If database required: add RDS instance or DynamoDB table
- Reference existing VPC and security group modules

### 3. Create Kubernetes Manifests
- Create /k8s/{service-name}/
- Include: deployment.yaml, service.yaml, configmap.yaml
- Set resource requests: 256Mi memory, 100m CPU
- Set resource limits: 512Mi memory, 500m CPU
- Configure health checks pointing to /health endpoint

### 4. Create CI/CD Pipeline
- Create /.github/workflows/{service-name}.yaml
- Include: lint, test, build, push to ECR, deploy to staging
- Production deploy should require manual approval

### 5. Update Service Registry
- Add entry to /infrastructure/services.yaml
- Include: name, owner, port, dependencies

## Verification
- [ ] Service directory exists with all required files
- [ ] Terraform plan runs without errors
- [ ] Kubernetes manifests pass kubeval validation
- [ ] CI/CD workflow syntax is valid
- [ ] Service registry is valid YAML

## Notes
- Always use the team's standard logging format
- All services must expose /health and /ready endpoints
- Database credentials go in SSM Parameter Store, never in code

This is hyper-specific to one codebase. It wouldn't work anywhere else. And that's exactly why it's valuable.

Why Generic Tools Fall Short

There's no shortage of tools promising to automate your workflows: scaffolding generators, infrastructure orchestrators, deployment platforms, AI coding assistants with plugin ecosystems.

The problem is that generic tools optimize for the general case. They have to work for everyone, which means they work perfectly for no one. You end up spending time:

• Learning the tool's abstractions and configuration language
• Figuring out how to make it work with your specific setup
• Working around limitations that don't apply to your use case
• Debugging why the tool isn't doing what you expected
• Keeping up with tool updates that break your customizations

The cognitive overhead of managing a generic tool often exceeds the overhead of just doing the task manually. Or worse, you become dependent on a tool you don't fully understand.

The Markdown Advantage

When your AI agent is a markdown file:

You can reason about it. There's no magic. No hidden configuration. No plugin behavior you need to trace through source code. The instructions are right there, in plain language.

AI can reason about it. Modern AI models excel at following well-structured natural language instructions. They can adapt to variations, handle edge cases, and ask clarifying questions—things rigid automation tools can't do.

It's trivially versionable. Put it in git. Review changes in pull requests. See the history of how your process evolved.

It's easily shareable. A new team member can read your agent files and understand not just what to do, but why. The documentation and the automation are the same artifact.

It's zero-dependency. No frameworks to install. No APIs to configure. No SaaS platforms to pay for. Just text files and an AI model.

Building Your Agent Library

Start by identifying repetitive tasks in your workflow. Look for processes that:

• You've done more than twice
• Have multiple steps that must happen in order
• Require knowledge of your specific codebase or infrastructure
• Are error-prone when done manually

For each one, write a markdown file. Be specific. Include the exact paths, the exact commands, the exact checks. Reference your actual file names, your actual conventions, your actual tools.

Some examples of agents I've found valuable:

• Add New API Endpoint - create route, handler, tests, documentation, and update OpenAPI spec
• Database Migration - create migration file, test locally, plan rollback strategy, update schema documentation
• Incident Response - check dashboards, gather logs, identify affected services, draft customer communication
• Security Patch - identify affected dependencies, test updates, create PR, verify CI passes
• New Team Member Setup - access requests, repository permissions, local environment configuration

The Human-AI Collaboration Model

This approach reframes the relationship between humans and AI. You're not trying to build an autonomous system that runs without supervision. You're creating a knowledgeable assistant that knows your codebase and your processes.

The human provides:

• The decision to execute a task
• Task-specific parameters (service name, feature description, etc.)
• Review and approval of the AI's work
• Judgment calls when situations are ambiguous

The AI provides:

• Execution of well-defined steps
• Consistency in following established patterns
• Speed in generating boilerplate and configuration
• Memory of details humans might forget

This division of labor plays to each party's strengths.

Getting Started

Pick one task you do regularly. Write it down in markdown, step by step, with all the specifics of your codebase. Then try giving it to an AI agent along with access to your codebase.

You'll probably need to refine the instructions. That's the point—you're encoding knowledge that previously only existed in your head. Each iteration makes the agent better, and the markdown document becomes living documentation of your process.

No framework required. Just clear thinking, plain text, and an AI that can read.