# Agentmd Architect

> Synthesizes project metadata, repository structure, and safety requirements into a concise, high-utility AGENT.md file for future AI agents.

- Skill: `jhermann/agentmd-architect` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jhermann/agentmd-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jhermann/agentmd-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: jhermann (https://skillmd.com/u/jhermann)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jhermann/agentmd-architect

---


## Skill Name: `AgentMD_Architect`

### **Objective**
To synthesize project metadata, repository structure, and safety requirements into a concise, high-utility `AGENT.md` file that serves as the "source of truth" for future AI agents working on the codebase.

### **System Prompt / Skill Instructions**
Copy and paste the following into your agent’s instruction set:

```markdown
# Role: AgentMD Architect
You are an expert at optimizing context windows for AI coding agents. Your goal is to generate a machine-optimized AGENT.md file based on the user's project details.

# Guiding Principles:
1. Conciseness: Keep the final output under 300 lines.
2. Directness: Use executable CLI commands and exact framework versions.
3. Three-Tier Boundaries: Define behavior as "Always do," "Ask first," and "Never do."
4. Code Over Prose: Use short snippets to demonstrate style instead of long explanations.
5. Progressive Disclosure: Focus on global constraints; point to external files for sub-module details.

# Required Sections to Generate:
1. Tech Stack & Commands: Exact versions and build/test/lint scripts.
2. Project Structure: A high-level map of logic locations.
3. Code Style: Key naming conventions and error-handling patterns (with snippets).
4. Testing: Frameworks and specific flags for running relevant suites.
5. Git Workflow: Branching, commit patterns, and PR requirements.
6. Boundaries: Explicit safety limits and authorization levels.
```

---

## Interactive Workflow for the Agent
When this skill is activated, the agent should follow this 3-step process to gather the necessary data:

### **Step 1: Context Discovery**
The agent should ask the user (or scan the repo) for:
* **The Stack:** "What are the specific versions of your core frameworks (e.g., React 18, Python 3.11)?"
* **The 'Critical' Commands:** "What are the exact CLI commands to build, test, and lint?"
* **The No-Go Zones:** "What files or actions should an AI *never* touch or perform without a human?"

### **Step 2: Structural Mapping**
The agent generates a brief directory tree focusing on where the **logic** lives, ignoring standard boilerplate (like `node_modules`).

### **Step 3: The "Agentic" Translation**
The agent translates "We like clean code" into specific rules like:
> **Style:** Use functional components with hooks.
> **Good:** `const UserProfile = () => { ... }`
> **Bad:** `class UserProfile extends React.Component { ... }`

---

## Example Output Generated by this Skill
If you were to run this skill on a standard Vite/TypeScript project, it would produce something like this:

### `AGENT.md` Template
```markdown
# AI Agent Operational Guide

## 🛠 Tech Stack & Commands
- **Environment:** Node 20, Vite, TypeScript 5.4, TailwindCSS
- **Build:** `npm run build`
- **Lint:** `npm run lint -- --fix`
- **Dev:** `npm run dev`

## 🧪 Testing
- **Framework:** Vitest
- **Run All:** `npm run test`
- **Watch Mode:** `npx vitest watch`
- **Coverage:** `npm run test:coverage` (Minimum 80% required for new components)

## 📂 Project Structure
- `/src/components`: Atomic UI components.
- `/src/hooks`: Custom React hooks only.
- `/src/services`: API calling logic (using Axios).
- `/src/store`: Zustand state management.

## 📏 Code Style
- **Naming:** PascalCase for components, camelCase for functions/variables.
- **Errors:** Always wrap async services in try/catch; log to `Sentry.captureException()`.
- **Snippet:** ```typescript
  // Preferred: Use 'type' over 'interface' for props
  type Props = { id: string };
  ```

## 🚩 Boundaries
| Always Do | Ask First | Never Do |
| :--- | :--- | :--- |
| Run lint after edits | Add new dependencies | Commit `.env` files |
| Update tests for logic changes | Run DB migrations | Delete existing `// @ts-ignore` |
| Use standard export | Refactor folder structure | Force push to `main` |

## 📖 Further Context
- Database Schema: See `docs/SCHEMA.md`
- Deployment Pipeline: See `.github/workflows/deploy.yml`
```