agents-md-guidelines
Guidelines for writing small, stable AGENTS.md files. Use when creating, refactoring, or reviewing AGENTS.md.
Best use case
agents-md-guidelines is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Guidelines for writing small, stable AGENTS.md files. Use when creating, refactoring, or reviewing AGENTS.md.
Teams using agents-md-guidelines should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/agents-md-guidelines/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How agents-md-guidelines Compares
| Feature / Agent | agents-md-guidelines | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Guidelines for writing small, stable AGENTS.md files. Use when creating, refactoring, or reviewing AGENTS.md.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
# AGENTS.md Guidelines ## Core Principles - Keep root AGENTS.md as small as possible; it loads on every request. - Use progressive disclosure: link to deeper docs for details. - Prefer stable concepts over volatile paths or time-sensitive notes. - Avoid “ball of mud” growth; don’t add rules for every mishap. - Keep instructions concise; assume the agent already knows basics. ## Essentials Only Root AGENTS.md should usually include: - One-sentence project description - Package manager if non-default - Non-standard build/typecheck commands - Pointers to deeper docs ## Progressive Disclosure - Move language, testing, and workflow rules into separate docs. - Link to those docs from AGENTS.md. - Keep guidance domain-based, not file-path based. - Avoid deep reference chains; link one level deep when possible. ## Staleness Rules - Avoid exact file paths unless they are stable interfaces. - Avoid dates or time-based instructions. - Prefer capability descriptions over structure hints. ## Monorepo Guidance - Use root AGENTS.md for shared rules. - Use package-level AGENTS.md for package-specific conventions. - Keep each level focused and minimal. ## Instruction Design - Start with a TL;DR checklist for fast scanning. - Include clear triggers and skip cases to prevent overuse. - Provide ordered steps with explicit outputs. - Use strict format rules with correct/incorrect examples. - Add a decision tree for edge cases when needed. - Include validation and debugging tips to reduce failure loops. - Make naming conventions explicit. - Define archive or completion criteria. - Keep terminology consistent. ## Quality Checklist - Description includes what + when, third-person. - Root AGENTS.md is short and link-heavy. - TL;DR + triggers + steps are present when needed. - No duplicated guidance across files. - Terminology is consistent. - Examples are concrete and brief. - Instructions fit an "instruction budget".
Related Skills
clack-guidelines
Comprehensive guide for building beautiful interactive command-line interfaces using Clack. Use when creating CLI tools with text input, selections, autocomplete, progress tracking, and streaming output.
agentsmd-claudemd-generator
Generate AGENTS.md and CLAUDE.md files for a repository. AGENTS.md provides cross-tool agent instructions (supported by Claude Code, Cursor, Windsurf, Zed, Codex, and others). CLAUDE.md adds Claude-specific configuration and references AGENTS.md via @import. Use when a repo needs agent onboarding or when starting a new project.
agents-md-generator
Generate comprehensive agents.md files for Builder.io Fusion projects. Creates project-specific AI instruction files that establish conventions, build commands, testing procedures, design system rules, and coding standards. Use when setting up a new project, onboarding a repository to AI-assisted development, or improving AI code generation quality.
agent-guidelines
When you need to understand the project's core mandate, operational rules, or "Constitution". Use this skill to align with the project's identity and strict coding standards.
documentation-guidelines
Write or update backend feature documentation that follows a repo's DOCUMENTATION_GUIDELINES.md (or equivalent) across any project. Use when asked to create/update module docs, API contracts, or backend documentation that must include architecture, endpoints, payloads, Mermaid diagrams, and seeding instructions.
developer-guidelines
Guidelines for the Developer role: strict adherence, no unsolicited refactoring, documentation, security.
artifact-guidelines
Guidelines for writing reports, organizing files, and generating code artifacts
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
vercel-web-design-guidelines
Reviews UI code for compliance with web interface best practices. Use when auditing accessibility, reviewing UI/UX patterns, checking performance, or improving web design quality. Triggers on "check my site", "audit design", "accessibility review", "UX best practices", or UI code review tasks. Covers 100+ rules for accessibility, performance, and user experience.
swift-human-guidelines
Comprehensive Swift 6 and SwiftUI development guidelines for building iOS 26, iOS 18, iPadOS, macOS, watchOS, visionOS, and tvOS applications. Covers Foundation Models API, BGContinuedProcessingTask, Call Translation API, Liquid Glass design system, data-race safety, typed throws, synchronization primitives, SwiftUI/UIKit interoperability, zoom transitions, and document-based apps. Use when building new Apple platform apps, implementing Apple Intelligence features, optimizing performance with Swift 6 concurrency, following Apple Human Interface Guidelines, creating cross-platform applications, or working with iOS 26/18 APIs. Triggers on Swift code, SwiftUI views, Xcode projects, app architecture, background processing, translation features, Foundation Models, synchronization, actors, Sendable types, or modern Apple platform development.
react-guidelines
React coding guidelines and best practices. MUST follow these rules. Use when reviewing or writing React code or tasks.
python-backend-guidelines
FastAPI/Django backend patterns and best practices