# Agdmigrate Agents Md > Migrate existing agent documentation to the standardized AGENTS.md format. Use when the user wants to convert, migrate, or port from AGENT.md, .cursorrules, .windsurfrules, CLAUDE.md, or contributing.md. Also triggers on 'convert .cursorrules to AGENTS.md', 'migrate agent docs', 'switch to AGENTS.md format'. Use when this capability is needed. - Skill: `tomevault-io/agdmigrate-agents-md` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/agdmigrate-agents-md` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/agdmigrate-agents-md/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/agdmigrate-agents-md --- Migrate existing agent documentation files to the standardized AGENTS.md format. Default to creating a compact single file; ask about references folder only for complex projects. ## Load Context Load the agents-md skill for format guidance: ``` Use Skill tool with skill="agd:agents-md" ``` Provides: sections, structure, symlink patterns, best practices ## Migration Sources Detect and migrate from common agent documentation files: | Source File | Detection | Migration Strategy | |-------------|-----------|-------------------| | `AGENT.md` | Single-file predecessor | Convert to AGENTS.md, ensure all sections covered | | `.cursorrules` | Cursor IDE rules | Extract rules, convert to AGENTS.md sections | | `.windsurfrules` | Windsurf IDE rules | Extract rules, convert to AGENTS.md sections | | `CLAUDE.md` | Claude Code instructions | Merge with AGENTS.md or convert | | `contributing.md` | Developer guidelines | Extract relevant sections for AGENTS.md | ## Process 1. **Detect source files**: ```bash ls -la | grep -E '(AGENT\.md|\.cursorrules|\.windsurfrules|CLAUDE\.md)' ``` 2. **If no source specified, auto-detect**: - Priority: AGENT.md > .cursorrules > .windsurfrules > CLAUDE.md - Prompt user if multiple files found 3. **Read and analyze source file**: - Identify existing sections - Extract commands, conventions, and guidelines - Note any missing recommended sections 4. **Transform to compact AGENTS.md format**: - Map existing content to recommended sections - Add missing sections based on project analysis - **Keep core AGENTS.md lean and actionable** (target: 50-80 lines) - Focus on essential commands and conventions - **Use relative paths** for references (e.g., `./docs/agents/testing.md`) - **For monorepos**: Add relative path references to sibling packages (e.g., `../api/AGENTS.md`) 5. **Create the new AGENTS.md**: - Write to ./AGENTS.md (or specified path) - Do not overwrite existing AGENTS.md without confirmation 6. **Ask about references folder** using AskUserQuestion (only if source was verbose or user wants detailed docs): ``` questions: [ { "question": "Would you like me to create a references folder for the detailed content from the original file?", "header": "References", "options": [ { "label": "No, single file is enough", "description": "Keep AGENTS.md as a simple, compact file. Recommended for most projects." }, { "label": "Yes, create docs/agents/", "description": "Create references folder and move detailed content there." }, { "label": "Yes, use custom path", "description": "Specify a custom path for the references folder." } ] } ] ``` **Only ask if**: - Original source file was verbose (>100 lines) - User explicitly wants to preserve all detailed content - Project has complex patterns needing documentation 7. **Create reference files** (if user chose yes): - Create detailed docs in references folder (e.g., docs/agents/) - Reference them from AGENTS.md 8. **Validate the migrated file**: - Check all commands are executable - Ensure all recommended sections present - Confirm no content lost in migration - Verify file is compact (under 100 lines) 9. **Handle original file**: Call AskUserQuestion: ```json { "questions": [{ "question": "What should I do with the original source file?", "header": "Original file", "options": [ {"label": "Create symlink", "description": "Run ln -sf AGENTS.md so it points to the new AGENTS.md."}, {"label": "Keep as-is", "description": "Leave the original file unchanged alongside AGENTS.md."}, {"label": "Delete original", "description": "Remove the original file after migration is complete."} ] }] } ``` - "Create symlink" → `ln -sf AGENTS.md ` - "Keep as-is" → no action - "Delete original" → `rm ` 10. **Ask about additional symlinks**: Call AskUserQuestion: ```json { "questions": [{ "question": "Would you like me to create symlinks for other AI agents?", "header": "Symlinks", "options": [ {"label": "No symlinks", "description": "Keep AGENTS.md as the only file."}, {"label": "Create CLAUDE.md", "description": "Symlink CLAUDE.md → AGENTS.md for Claude Code compatibility."}, {"label": "Create all symlinks", "description": "Create CLAUDE.md, .cursorrules, and .windsurfrules all pointing to AGENTS.md."} ] }] } ``` - "No symlinks" → Done - "Create CLAUDE.md" → `ln -sf AGENTS.md CLAUDE.md` - "Create all symlinks" → `ln -sf AGENTS.md CLAUDE.md && ln -sf AGENTS.md .cursorrules && ln -sf AGENTS.md .windsurfrules` ## Content Mapping Transform common patterns: | Source Pattern | AGENTS.md Section | |----------------|-------------------| | "Run tests with..." | Testing instructions | | "Code style: ..." | Code style | | "Before committing..." | PR instructions | | "Environment setup..." | Setup commands | | "Security notes..." | Security | ## Example Transformation ```markdown # Before (verbose .cursorrules, 80 lines) ## Code Style - Use TypeScript strict mode - Single quotes for strings - No semicolons - Max line length: 100 characters - Functional components with hooks - Colocate tests next to components - Use meaningful variable names - Avoid any type - Prefer const over let - Document complex functions with JSDoc [... 50 more lines of detailed conventions ...] # After (compact AGENTS.md, 60 lines) ## Code style - TypeScript strict mode - Single quotes, no semicolons - Functional components with hooks ## PR instructions - Use Conventional Commits (see agd:conventional-commits skill) - Run `pnpm lint && pnpm test` before pushing ``` ## Validation Checklist After migration, verify: - [ ] All commands are executable - [ ] All recommended sections present (or intentionally omitted) - [ ] Original content preserved (nothing lost) - [ ] Format follows skill best practices - [ ] File is concise (ideally under 100 lines) - [ ] References folder only created if user wanted it ## Notes - Always load the agents-md skill for context - **Default to compact**: Create a simple AGENTS.md first - Preserve all original content - migration should not lose information - Only ask about references folder for verbose sources - Ask user before deleting original files - Validate migrated file before completing - Offer symlink creation for backward compatibility --- > Source: [Christophe1997/agent-extentions](https://github.com/Christophe1997/agent-extentions) — distributed by [TomeVault](https://tomevault.io).