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.