Building an AI Agent That Writes Perfect READMEs for You

For HNG Stage 2, we were challenged to build an AI agent and integrate it with Telex , a Slack-like workspace where humans and AI agents can collaborate.
The agent needed to be simple, useful, and solve a real problem.

As a backend developer, I immediately thought of one universal pain every developer shares:

Writing a good README.

So, I built Zainab Readme Agent, an AI agent that automatically generates polished, professional READMEs for GitHub repositories.

---

🚀 What It Does

The workflow is beautifully simple:

1. Drop a GitHub repository URL

2. Get a complete, formatted, and professional README.md in seconds

No more blank README.md files or copy-pasting from templates.

---

Getting Started

This was my first time building an AI agent, and I was genuinely excited (and a bit nervous).
The brief required using Mastra, a lightweight framework for creating AI agents, and integrating it with Telex via the Agent-to-Agent (A2A) protocol.

Since I’d never used either tool, I began by reading documentation and experimenting.
Two key resources helped me understand how things fit together:

• A guide on building AI agents with Mastra

• An article explaining Telex A2A protocol, a standardized way for agents to communicate and interact seamlessly

Once I understood the basics, I got to work.

---

The Idea

Every GitHub project starts with a blank README.md, and writing one often feels like a chore.
So my idea was to build an agent that could:

• Read and analyze a repository’s files

• Understand its purpose, language, and framework

• Generate a polished, engaging README

• Improve existing READMEs automatically

• Work directly inside a Telex workspace for team use

In short: turn repository metadata into documentation magic.

---

Step 1 – Initialize the Mastra Project

I started with:

npm create mastra@latest

This sets up a Mastra project (it even comes with a sample weather agent you can experiment with).

---

Step 2 – The Core Agent

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/libsql";
import { getRepoDetailsTool } from "../tools/readme-agent";

export const readmeAgent = new Agent({
  name: "Readme Agent",
  instructions: `
    You are a professional technical writer.
    Given the repository metadata and key files, write a **complete, polished README.md** in Markdown.
    Include sections for:
    - Project title & tagline
    - Badges (stars, license, language)
    - Description
    - Installation
    - Usage / Quick start
    - API / Configuration (if applicable)
    - Contributing
    - License

    If a README already exists, **improve** it – keep good parts, add missing sections, fix grammar, and make it more engaging.
  `,
  model: "google/gemini-2.5-flash",
  tools: { getRepoDetailsTool },
  memory: new Memory({
    storage: new LibSQLStore({
      url: "file:../mastra.db",
    }),
  }),
});

Why this works:

• instructions = The entire “prompt engineering” magic

• gemini-2.5-flash = Free, fast, and smart

• memory = Keeps context for follow-up edits (“make it shorter”, “add emoji”, etc.)

---

Step 3 – The Tool

export const getRepoDetailsTool = createTool({
  id: "get-repo-details",
  description: "Fetch metadata + key files from a public GitHub repository",
  inputSchema: z.object({
    repoUrl: z.string().url(),
  }),
  execute: async ({ context }) => {
    const { repoUrl } = context;
    const [, owner, repo] = repoUrl.match(/github\.com[\/:]([^\/]+)\/([^\/]+?)/) || [];

    const repoRes = await axios.get(`${GITHUB_API}/repos/${owner}/${repo}`);
    const repoData = repoRes.data;

    const readme = await fetchFile(owner, repo, "README.md")
      || await fetchFile(owner, repo, "readme.md");

    return {
      name: repoData.name,
      description: repoData.description,
      stars: repoData.stargazers_count,
      language: repoData.language,
      license: repoData.license?.spdx_id ?? null,
      topics: repoData.topics,
      readme,
      packageJson: await fetchFile(owner, repo, "package.json"),
      pyprojectToml: await fetchFile(owner, repo, "pyproject.toml"),
      cargoToml: await fetchFile(owner, repo, "Cargo.toml"),
    };
  },
});

Magic parts:

• Detects multiple README name formats

• Fetches package.json, pyproject.toml, and Cargo.toml for better context

• Returns clean metadata for the AI to build from

---

Step 4 – The Brain (Mastra Server)

import { Mastra } from "@mastra/core/mastra";
import { readmeAgent } from "./agents/readme-agent";
import { a2aAgentRoute } from "./routes/readme-route";

export const mastra = new Mastra({
  agents: { readmeAgent },
  server: {
    apiRoutes: [a2aAgentRoute], // allows Telex to call the agent
  },
  bundler: {
    externals: ["axios"],
  },
});

That’s it.
One file = fully working backend.

---

Step 5 – Deploy

Step 5 – Deployment (via GitHub + Mastra Dashboard)

I couldn’t deploy from the terminal using mastra deploy, so instead, I:

1. Pushed my project to GitHub

2. Opened the Mastra Dashboard

3. Connected my GitHub repo and deployed directly from there

I then got the URL for my project and used it for Telex integration

---

Step 6 – Telex Integration

Telex lets humans and AI agents work together in one workspace.

To connect my agent, I imported this simple JSON config:

{
  "active": true,
  "category": "utilities",
  "description": "A workflow that generates readme for a repository",
  "id": "sGC3u7y4vBaZww0G",
  "name": "readme_agent",
  "long_description": "You are a professional technical writer.\nGiven the repository metadata and key files, write a **complete, polished README.md** in Markdown.\nInclude sections for:\n- Project title & tagline\n- Badges (stars, license, language)\n- Description\n- Installation\n- Usage / Quick start\n- API / Configuration (if applicable)\n- Contributing\n- License\n\nIf a README already exists, **improve** it – keep the good parts, add missing sections, fix grammar, and make it more engaging.\n\nGuidelines:\n- Be concise but thorough\n- Use proper Markdown formatting\n- Include code blocks with appropriate syntax highlighting\n- Make it engaging and easy to follow\n- Infer missing information intelligently from the codebase\n- If you can't find certain information, use reasonable defaults or skip that section\n\nOutput the complete README content in Markdown format.",
  "short_description": "Generate readme for a repository",
  "nodes": [
    {
      "id": "readme_agent",
      "name": "readme agent",
      "parameters": {},
      "position": [816, -112],
      "type": "a2a/mastra-a2a-node",
      "typeVersion": 1,
      "url": "https://brown-lemon-country.mastra.cloud/a2a/agent/ReadmeAgent"
    }
  ],
  "pinData": {},
  "settings": {
    "executionOrder": "v1"
  }
}

This integration allows Telex users to directly call the readme_agent and get README files generated from any GitHub repo link.

---

💡 What I Learned

• How AI agents can automate tedious developer tasks

• How Mastra simplifies building, connecting, and deploying them

• How Telex enables real-time human + AI collaboration

• How powerful clear prompt engineering and context are when working with models

This project gave me hands-on experience with AI integration, backend logic, and real-time collaboration tools, all in one sprint.

---

Links

• Source Code: github.com/zainabwahab-eth/Readme-agent

---

This project started as an HNG challenge — but it became my first real step into building intelligent developer tools that actually make life easier.

And now… I never have to write a README manually again 😄