English | 한국어
An Agent Skills collection that generates and validates AGENTS.md based on best practices, so AI agents can understand your project and work consistently. Whether you're a solo developer or a team, telling agents your project's rules leads to better results.
Agent Skills can be installed via Vercel's skills.sh. However, once a skill is installed locally, it does not auto-update. To address this, every skill in this project performs its own update check at invocation time. When a new version ships or a skill is renamed, you get notified immediately — so you stay on the latest version even as the collection keeps evolving.
Since the emergence of Agent Skills, various harnesses have appeared for building polished products. These tools leverage on-demand loading and slash commands effectively, and I use a mix of my own skills and open-source tools in my workflow.
However, always-loaded documents like CLAUDE.md, AGENTS.md, and .cursorrules are known to suffer from declining compliance as they grow longer. Some argue that base instruction files are unnecessary, but I believe Agent Skills and base instruction files are complementary:
- Agent Skills → "How to perform this task" (on-demand)
- Base instruction files → "How we work in this project" (always applied)
Consistent rules matter especially in team settings. If everyone uses the same agent, a single CLAUDE.md or .cursorrules might suffice. In practice, however, people switch between agents or use different tools. AGENTS.md is natively read by most major agents — Cursor, GitHub Copilot, Windsurf, Codex CLI, and more — and the rest can be connected with a simple bridge.
The content this project provides is mostly well-known practices. But unlike Agent Skills, base instruction files sit in the always-on context and need careful context engineering — concise yet relevant as the project evolves. This project simplifies that process.
The skills in this project follow these principles:
Separate public rules from private rules — Public rules (build commands, code style, boundaries) go in AGENTS.md (git-tracked). Private rules (your workflow preferences, response language) go in local files like CLAUDE.local.md (git-ignored). Even solo developers benefit from public rules — they help agents understand your project better, and serve as documentation for teammates or your future self.
What to include — Only information that agents cannot infer from code or config files. Build/test commands (with flags), code style (as code examples), boundaries (Always do / Ask first / Never do), and project-specific pitfalls.
What NOT to include — Self-evident advice like "write clean code", rules already enforced by linters/formatters, anything readable from the code. The more instructions you add, the less agents comply.
Right size — Start under 150 lines. Never exceed 300.
References:
- GitHub Blog: How to write a great agents.md — Recommendations based on 2,500+ repos
- Augment Code: How to Build Your AGENTS.md — Performance experiments by length
- Anthropic: Best Practices for Claude Code — CLAUDE.md / CLAUDE.local.md separation
- AGENTS.md spec — The standard
The skills now cover the full AGENTS.md lifecycle: create the header, manage each section with a dedicated skill, and orchestrate work units end-to-end. The ultimate goal is an environment where my team and I can collaborate with AI agents more comfortably. The next expansion we're planning:
Best-practices auto-tracking — Resources on open standards like AGENTS.md and Agent Skills are accumulating rapidly. We're exploring a tracking system that periodically collects relevant materials and automatically improves the skills to reflect evolving best practices.
Details will be added to this document and the roadmap as each feature takes shape.
| Skill | Description |
|---|---|
| init-public-rules | Generate AGENTS.md (public agent instructions) + auto-configure bridge files. Shallow setup covering only the project header plus optional Project Structure / Code Style / Testing. |
| init-private-rules | Auto-detect the current agent and create a git-ignored private config file. |
| migrate-rules | Consolidate scattered agent configs (.cursorrules, CLAUDE.md, etc.) into AGENTS.md. |
| Skill | Description |
|---|---|
| manage-tools | Manage the ## External Tools section. Three fixed categories (Agent Skills / MCP Servers / CLIs). Auto-detects candidates from project config files (.mcp.json, package.json, mise.toml) and presents a checklist. Drift detection on re-run. |
| git-workflow | Manage the ## Git Workflow section. Three fixed presets (Trunk-based / GitHub Flow / GitFlow) plus a delta interview. Auto-detects the closest preset from git log. |
| refine-boundaries | Accumulate the ## Boundaries section iteratively from agent mistakes. Classifies each rule into Always do / Ask first / Never do, and decides whether it belongs inline in a topic section or cross-cutting in Boundaries. |
| manage-refs | Add, remove, and verify pointers (PRDs, ERDs, ADRs, etc.) inside the ## References section. Forbids @ import syntax. |
| Skill | Description |
|---|---|
| work-unit-ritual | Encode a 6-step ritual (plan → discuss → register → implement → completion check → close) into AGENTS.md and execute one work unit at runtime using the stored spec. Requires an issue tracker CLI and ## Git Workflow to be set up first. |
| Skill | Description |
|---|---|
| audit-rules | Diagnose agent instruction files, then optionally improve them with user approval. |
| agent-collabo-updater | Update only the changed skills (handles removals, renames, and new skills automatically). |
These skills assume you've installed them and are running an agent (Claude Code, Cursor, etc.) inside a new or in-progress project. The more your project has set up — build/test tooling, directory structure, a Git repo — the more accurate the automated analysis becomes and the shorter the interview gets. Each skill can be triggered by keywords, but invoking the slash command explicitly is recommended.
To set up AI agent rules in a new or in-progress project — Run /init-public-rules. It runs automated analysis and a short interview, then generates AGENTS.md (public, git-tracked) and the bridge files.
To keep your own working style, response language, or local environment separate from the team-shared rules — Run /init-private-rules. It auto-detects the agent you're using and creates the matching private config file (CLAUDE.local.md, etc., git-ignored).
When an existing project already has scattered agent config files (.cursorrules, CLAUDE.md, .github/copilot-instructions.md, etc.) — Run /migrate-rules. It consolidates the contents into AGENTS.md, removes duplicates, and converts the old files into bridges. Where /init-public-rules is the tool for "creating AGENTS.md or extending an existing one", /migrate-rules is the tool for "gathering many agent config formats into a single place".
After writing rule files, or when the quality of long-running rule files starts to feel off — Run /audit-rules. It diagnoses length, anti-patterns, token efficiency, and structure, then improves them with your approval.
To tell the agent about tools this project depends on — Run /manage-tools. It scans .mcp.json, package.json, mise.toml, and similar config files to propose candidates as a checklist, asks for a one-line "when to use" for each selected tool, and writes the ## External Tools section. Re-running it detects drift between what's installed and what's documented.
To define branch, commit, and PR conventions — Run /git-workflow. Pick one of three presets (Trunk-based / GitHub Flow / GitFlow) and fill in project-specific customizations via a checklist (ticket prefix, PR title format, release tag format, etc.). The skill analyzes git log to pre-select the closest matching preset.
To build up ## Boundaries rules every time the agent makes a mistake — Run /refine-boundaries. Describe what the agent did wrong as a one-line imperative, and the skill classifies it into Always do / Ask first / Never do, decides whether it belongs inline in a topic section (Code Style / Testing / Git Workflow) or cross-cutting in Boundaries, and places it accordingly.
To point the agent at planning or design documents — Run /manage-refs. It registers a file path into ## References as a single line (`path/to/doc.md` + one-line description). No @path imports — the agent reads the file on demand when needed.
To run one work unit end-to-end as a ritual — Run /work-unit-ritual. On first run, it encodes a 6-step ritual (plan → discuss → register → implement → completion check → close) into ## Git Workflow. On subsequent runs, it follows the stored ritual to execute one work unit. Prerequisites: /git-workflow and /manage-tools must have set up the Git workflow and registered an issue tracker CLI (gh, glab, etc.) first.
When a new version of the skills themselves ships — Each agent-collabo skill performs a version check at invocation, so a new version surfaces a notification automatically. When you want to apply the update, follow the prompt and run /agent-collabo-updater at a time of your choosing. It updates only the changed skills, removes deprecated ones, and migrates renamed skills automatically.
Most projects benefit from agent instruction management, so a global install is recommended.
# Global (recommended)
npx skills add dev-goraebap/agent-collabo --all -g
# Project-scoped
npx skills add dev-goraebap/agent-collabo --allThe
--allflag installs every skill at once. To install only specific skills, drop--alland pick the ones you want from the selection step.
Every skill in this project fetches the repo's manifest.json at invocation and compares it against its local version. It's a single HTTP request and works regardless of installation scope (global or project).
| Situation | Behavior |
|---|---|
| Up to date | Proceed silently |
| New version available / renamed | Show "run /agent-collabo-updater" notice and continue with the current task |
| Skill is no longer maintained | Warn, then proceed |
Updates are applied through the dedicated /agent-collabo-updater skill. It updates only the changed skills, removes deprecated ones, and migrates renamed skills automatically. Both global and project scopes are supported.
/agent-collabo-updater
This is independent from
npx skills check/update. It fetches a single raw file from GitHub, so it's fast.
| Agent | AGENTS.md Support | Bridge |
|---|---|---|
| Cursor, GitHub Copilot, Windsurf, Codex CLI, Junie, Roo Code, Amp, Devin | Native | Not needed |
| Claude Code | Not supported | .claude/CLAUDE.md → @../AGENTS.md |
| Gemini CLI | Requires config | Guidance message |
- Public & private rules management (init-public-rules, init-private-rules, audit-rules, migrate-rules)
- Skill change notifications (manifest-based update check)
- Section-specific management skills (manage-tools, git-workflow, refine-boundaries, manage-refs)
- Work-unit orchestrator (work-unit-ritual)
- Track evolving best practices & automate skill improvements