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:

Process

1. Detect source files:

   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:

   {
     "questions": [{
       "question": "What should I do with the original source file?",
       "header": "Original file",
       "options": [
         {"label": "Create symlink", "description": "Run ln -sf AGENTS.md <original-file> 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 <original-file>
   • "Keep as-is" → no action
   • "Delete original" → rm <original-file>

10. Ask about additional symlinks:

    Call AskUserQuestion:

    {
      "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:

Example Transformation

# 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 — distributed by TomeVault.