hackycy/init-agents-md

Initialize AGENTS.md

Create contributor guidelines for a repository root or an existing directory. The sole source for output format and recommended sections is references/agents-md-prompt.md; this skill is responsible for safely applying that fixed instruction to the correct scope.

Input & Scope

• Accepts zero or one directory argument; relative paths are resolved against the current working directory. With no argument, uses the Git root found via git rev-parse --show-toplevel.
• An explicit directory may be outside a Git repository; when no argument is given and no Git root is found, prompt the user to specify a directory and stop. The path must resolve to a readable directory; stop on missing paths, files, non-readable directories, or multiple directory arguments.
• The default candidate output is AGENTS.md in that directory. Only one scope is processed at a time; no directories are created, no other files are modified, and nothing is staged, committed, or branched.
• Follow the primary language of local documentation; use English when signals are insufficient. If the selected directory is not the repository root, prepend ## Scope at the top stating the relative directory and applicable parent guidelines; only write locally added or narrowed rules.

Reconnaissance Before Generation

1. Before drafting, read the target and necessary project context: directory structure, manifest/lockfile, scripts, build/test/lint configuration, CI, README/CONTRIBUTING, and up to 30 relevant commits if Git is available. Identify monorepo package boundaries, package managers, and the primary language of local documentation.
2. Find all relevant AGENTS.md files: the target file, ancestor files from the repository root to the target's parent directories, and nested files within the target's subtree. For non-Git directories, check ancestor chain. For subtrees, check direct subdirectories first; expand only when manifests, package boundaries, or existing guides point deeper; skip .git, dependencies/vendor, build/coverage output, cache, and ignored secret stores.
3. Tag matches as target, ancestor, or nested, and read CLAUDE.md, CONTRIBUTING.md, and related guides as constraints. For nested guides, only read, preserve, and link to them; do not merge or modify them.
4. Only check filenames and metadata for potential secret files. Never read or write keys, tokens, credentials, or .env contents.
5. Every command and convention must be verifiable by scripts, configuration, existing files, or history. Distinguish observed repository rules from generic default recommendations; omit sections, commands, or assertions without evidence.

Matching Guide Confirmation

Before generating a draft, display all matches, their scopes, and the candidate output path, and check for case conflicts (e.g., agents.md). This is a hard gate:

• If the candidate target already exists, read it and ask the user to choose merge, replace, or abort.
• If the target does not exist but ancestor or nested guides are found, ask the user to explicitly choose between "create a new guide for this scope" or "update an existing named guide"; do not silently add a child file. If another existing file is chosen, redo reconnaissance for that file's directory before selecting the mode again.
• If no matches are found, proceed to draft a new file for the original target.
• Stop and report the reason if the selected AGENTS.md is a symlink, directory, special file, or non-writable regular file.

Any unanswered or ambiguous choices, or conflicts with guides like CLAUDE.md, leave the workspace unchanged.

Read the Fixed Instructions

Read references/agents-md-prompt.md fully before starting the draft. It is the canonical owner for headings, documentation requirements, recommended sections, word count targets, and expression style; do not modify it during normal operation, and do not duplicate its body in this skill.

Merge, Preview & Write

merge merges by Markdown heading semantics: preserve existing facts and custom sections, only supplement missing content that has evidence. Present all command, path, priority, or fact conflicts in a table and let the user pick per-item whether to keep existing, adopt evidence, or provide custom text; do not write while unresolved conflicts exist. replace only affects the selected single file; no automatic backup is generated.

For new files, show the full draft; for updates, show a unified diff with a summary of path, scope, sections, word count, evidence gaps, and mode. Do not create or modify files before explicit final write confirmation from the user; if modifications are requested, go back to drafting and previewing. Before writing, re-read the target; if content was externally changed, re-run the confirmation flow.

Validation & Completion

Before writing, check headings, heading levels, scope links for nested guides, referenced paths/scripts, placeholders, sensitive values, and Markdown whitespace. For root guides, check against the word count target in the fixed instructions; for nested increments, check roughly 100–300 words. Only auto-fix mechanical issues like trailing spaces, duplicate blank lines, etc., and preview again; leave semantic or factual issues to the user. If the target is in Git, run git diff --check; otherwise, do an equivalent whitespace check. Do not run a full build, test, or lint by default for this skill.

Completion conditions: confirmed AGENTS.md exists at the selected path, passes static checks, and matches the approved preview. Final report states mode, scope, verified commands, omitted/uncertain items, and validation results. On user abort or failed validation, report the reason and leave the target unchanged.