Agent skill · writing content · mcollina
init
Creates, updates, or optimizes an AGENTS.md file for a repository with minimal, high-signal instructions covering non-discoverable coding conventions, tooling quirks, workflow preferences, and project-specific rules that agents cannot infer from reading the codebase. Use when setting up agent instructions or Claude configuration for a new repository, when an existing AGENTS.md is too long, generic, or stale, when agents repeatedly make avoidable mistakes, or when repository workflows have changed and the agent configuration needs pruning. Applies a discoverability filter—omitting anything Claude can learn from README, code, config, or directory structure—and a quality gate to verify each line remains accurate and operationally significant.
Why this skill is useful
Adds specific guidelines for creating and maintaining AGENTS.md files, which are crucial for agent performance and not commonly found in public documentation.
What it needs
About 2k tokens when loaded. Last updated 2026-08-03. 1,894 stars on the source repository.
What this skill does
When to use Use this skill when creating or updating AGENTS.md for a repository. Use it especially when: the current AGENTS.md is long, generic, or stale agents repeatedly make the same avoidable mistakes repository workflows changed and agent guidance needs pruning Instructions Treat AGENTS.md as a living list of non-discoverable landmines and workflow gotchas, not a codebase overview. Core rule: discoverability filter Before adding any line, ask: Can an agent discover this by reading the repo (README, code, config, scripts, directory tree)? If yes: do not include it in AGENTS.md. If no, and it materially affects task success/cost/safety: include it. What earns a line Include only guidance that is: 1. Non-discoverable from repository files alone 2. Operationally significant (changes commands, outcomes, or safety) 3. Actionable (specific enough to execute) Typical examples: Non-standard tooling choices (e.g. use uv instead of pip) Command caveats (e.g. tests must run with --no-cache due to fixture behavior) Hidden constraints/landmines (deprecated directories still imported in production) Critical local conventions that are not encoded in lint/tests/config What to remove or avoid Do not include: Tech stack summaries Directory structure overviews Architecture descriptions agents can infer from code Generic best-practice advice Rules already enforced by tooling (linters, typecheck, tests, CI) Mandatory boilerplate headers unless the repo explicitly requires one Recommended structure Prefer short, high-signal sections such as: Scope & routing (which areas need separate/module-local AGENTS files) Non-discoverable commands Landmines / do-not-touch areas Task-specific constraints For large repos, recommend hierarchical AGENTS.md files near relevant modules instead of one monolithic root file. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills mcollina/init