Universal Agents

A "polyfill" that standardizes and centralizes AGENTS.md configuration and Agent Skills support within your repository.

Installation

curl -fsSL https://raw.githubusercontent.com/agentsmd/universal-agents/main/install.sh | sh

What This Does

Brings standardized and centralized support for AGENTS.md and Agent Skills to major AI coding agents. Most agents have incomplete or broken support natively - this fixes that.

AGENTS.md features:

📄 Basic support: Agents automatically read AGENTS.md files instead of (or in addition to) their proprietary formats

🪺 Nested: Nested AGENTS.md files apply with proper precedence (closer = higher priority)

🎯 Selective: Only loads relevant AGENTS.md files, not all of them (essential for large monorepos)

Skills features:

🔧 Shared skills: Store skills once in .agents/skills/, use across all agents

♻️ Native integration: Skills symlink to each agent's native directory for hot reload and discovery

Philosophy

AI coding agents shouldn't fragment your configuration. This project enables:

• Universal format - Write AGENTS.md once, use it across major AI agents (Claude Code, Cursor, Gemini)
• Standard locations - .agents/ and AGENTS.md files in predictable places, not scattered proprietary formats
• No rebuild step - Edit AGENTS.md files, they just work. No commands to run after changes.
• Native behavior - Leverage each agent's built-in features (hot reload, skill discovery, etc.)
• Simple and portable - Shell scripts only. Works everywhere with no dependencies.

Native Support

Out of the box, most agents have incomplete or missing AGENTS.md support:

How It Works

Claude Code: SessionStart hook that implements AGENTS.md with no CLAUDE.md files or symlinks needed

Gemini CLI: Native configuration pointing to AGENTS.md in addition to GEMINI.md

Usage

Create AGENTS.md files anywhere in your project. They'll be loaded automatically with proper scoping:

project/
├── AGENTS.md              # Applies project-wide
└── src/
    └── api/
        └── AGENTS.md      # Applies to API work (overrides project-wide)

When working in src/api/, both AGENTS.md files apply - with the API-specific one taking precedence for conflicts (🪺 nested).

Agents load context only for the directories you're working in, keeping token usage efficient even in large projects (🎯 selective).

Skills

Store skills in .agents/skills/ and they'll be available to all configured agents:

.agents/
└── skills/
    └── my-skill/
        └── SKILL.md

Skills are symlinked to each agent's native skills directory (e.g., .claude/skills/), enabling:
- Native skill discovery
- Hot reloading
- Cross-agent compatibility

See Agent Skills Specification for SKILL.md format.

Troubleshooting

Skills not showing up?
- Check that the symlink exists (e.g., .claude/skills -> ../.agents/skills)
- Try restarting the agent session
- Note: Claude Code's /skills command has a display bug with symlinked directories - skills still work

"Warning: directory exists" during install?
- Move existing skills from .claude/skills/ to .agents/skills/
- Re-run the install script

Global install first run?
- After installing globally, restart your agent session for hooks to take effect

License

This project is licensed under the Blue Oak Model License, Version 1.0.0, but you may also license it under Apache License, Version 2.0 if you—or your legal team—prefer.