agents-md

Refactor AGENTS.md files into linked documents using progressive disclosure.

8|4|Updated Jan 15, 2026

Search Tags:#documentation #markdown #refactoring #agents #progressive disclosure #contractions

Ready to run

npx skills add https://github.com/jscraik/Agent-Skills --skill agents-md-jscraik

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: agents-md
Source: https://github.com/jscraik/Agent-Skills/tree/main/product/docs/agents-md
Command: npx skills add https://github.com/jscraik/Agent-Skills --skill agents-md-jscraik

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill addresses the challenge of maintaining large, complex, and potentially contradictory documentation for AI agents by refactoring it into a more manageable and discoverable format.

Core Features & Use Cases

Progressive Disclosure: Organizes documentation by keeping the root AGENTS.md file concise and routing detailed instructions to linked files.
Contradiction Detection: Identifies and flags conflicting instructions within the documentation.
Use Case: When your AGENTS.md file becomes a lengthy monolith, use this skill to split it into a high-level overview and detailed guides for specific commands, ensuring clarity and reducing cognitive load for users.

Quick Start

Use the agents-md skill to refactor the AGENTS.md file for progressive disclosure.

Frequently Asked Questions about agents-md

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

FAQPage Schema

What is progressive disclosure in AI agent documentation?▼

Refactoring a lengthy AGENTS.md file involves splitting it into a concise root overview and linked detailed guides. This progressive disclosure approach ensures clarity, reduces duplication, and organizes instructions for specific commands.

How do I fix contradictory instructions in my AGENTS.md file?▼

To fix contradictory instructions in your documentation, use a refactoring process that detects and flags conflicting guidelines. It then reorganizes the content into linked files to eliminate redundancy and resolve contradictions.

How do I split a large AGENTS.md file into linked documents?▼

Splitting a large AGENTS.md file involves breaking the monolith into a high-level overview and detailed guides for specific commands. This ensures the root guidance remains minimal while routing detailed instructions to linked documents.

When should I refactor my AI agent markdown documentation?▼

You should refactor your AI agent markdown documentation when it becomes a lengthy monolith with duplicated or contradictory instructions. This is necessary when the file size causes cognitive overload and hinders discoverability.

Does progressive disclosure work for resolving markdown redundancy?▼

Yes, progressive disclosure works for resolving markdown redundancy by keeping the root AGENTS.md file minimal and routing detailed instructions to linked documents. It actively flags contradictions and reduces duplicated content across the documentation.