agents-md-refactor

Reorganize AGENTS.md files into linked topic files with a minimal root.

Updated Mar 19, 2026
One-click install
npx skills add https://github.com/japurcell/skills --skill agents-md-refactor
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: agents-md-refactor
Source: https://github.com/japurcell/skills/tree/main/skills/agents-md-refactor
Command: npx skills add https://github.com/japurcell/skills --skill agents-md-refactor

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Reorganizes AGENTS instruction docs into a progressive-disclosure structure by moving domain-specific guidance into linked topic files while preserving a minimal root AGENTS.md.

Core Features & Use Cases

  • Minimal root: Create a short, always-load-safe root AGENTS.md that contains only essential guidance.
  • Topic-driven organization: Move domain-specific rules into linked topic files to reduce clutter and improve maintainability.
  • Conflict resolution workflow: Detect contradictions and surface choices for user-directed decisions before applying changes.

Quick Start

Generate a minimal root AGENTS.md and create linked topic files for major guidance areas.

Frequently Asked Questions about agents-md-refactor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refactor AGENTS.md documentation into linked topic files?

You refactor AGENTS.md documentation by moving specialized rules into linked topic files while preserving a minimal root AGENTS.md, establishing a progressive-disclosure structure that separates concerns and reduces duplication.

What is progressive-disclosure structure for agent instruction docs?

Progressive-disclosure structure for agent instruction docs means maintaining a short, always-load-safe root AGENTS.md that contains only essential guidance, while linking out to topic files for domain-specific rules to reduce clutter and improve maintainability.

How do I resolve conflicts when reorganizing AGENTS instruction documentation?

When reorganizing AGENTS instruction documentation, you resolve conflicts by detecting contradictions during the refactoring process and surfacing choices for user-directed decisions before applying structural changes to the files.

Can I apply scoped AGENTS file refactoring across multiple repository directories?

Yes, scoped AGENTS file refactoring applies to both the root AGENTS.md and scoped AGENTS files across the repository, enabling clean separation of concerns and easier maintenance for domain-specific guidance in any directory.

Why does my AGENTS.md file need a minimal root and linked topic files?

Your AGENTS.md file needs a minimal root with linked topic files because moving domain-specific guidance out of the root reduces clutter, avoids duplication, and creates an always-load-safe entry point that improves overall documentation maintainability.