Instead of relying on engineers to remember documented procedures (e.g., pre-commit checklists), encode these processes into custom AI skills. This turns static best-practice documents into automated, executable tools that enforce standards and reduce toil.

An internal OpenAI team maintains a codebase written entirely by AI. By removing the "escape hatch" of manual coding, they are forced to solve fundamental problems in providing better context and documentation to the AI, thus uncovering best practices for agent interaction.

The simple, text-based structure of Markdown (.md) files is uniquely suited for both AI processing and human readability. This dual compatibility is establishing it as the default file format for the AI era, ideal for creating knowledge bases and training documents that both humans and agents can easily use.

"Skills" are markdown files that provide an AI agent with an expert-level instruction manual for a specific task. By encoding best practices, do's/don'ts, and references into a skill, you create a persistent, reusable asset that elevates the AI's performance almost instantly.

As AI handles code generation, the most durable asset engineers create will shift from the code itself to the documentation that guides the AI. This documentation captures the 'why'—the intention, PRD, and customer problem—making it the essential input for future AI-driven development and iteration.

Intercom noticed AI-generated pull request descriptions were poor. Instead of a wiki, they built a mandatory "Create PR" skill that enforces high-quality, intent-focused descriptions, turning a cultural standard into an automated process.

The 'agents.md' file is an open format that functions like a README, but specifically for AI agents. It provides a dedicated, predictable place to store context and instructions, ensuring the AI consistently follows rules for commits, tests, and project setup across all your repositories.

Documentation is shifting from a passive reference for humans to an active, queryable context for AI agents. Well-structured docs on internal APIs and class hierarchies become crucial for agent performance, reducing inefficient and slow context window stuffing for faster code generation.

Engineering AI tools understand markdown better than complex PRDs in other formats. Product leaders can translate critical user workflows into simple markdown files, providing context to the AI to help it analyze the impact of code changes and identify potential issues.