agents-md-generator — Skillopedia

AGENTS.md / CLAUDE.md Generator Overview This skill helps you generate comprehensive instruction files (AGENTS.md with optional CLAUDE.md compatibility) that teach AI coding agents how to work effectively in your project. It combines automatic project scanning with interactive questions to create tailored guidelines. When to use this skill: - Setting up a new project for AI-assisted development - Updating existing instruction files after project changes - Standardizing AI agent behavior across team members - Migrating from one AI tool to another Key Principle Do not duplicate specialized skil…

\\t' read -r completed_header_line section_start section_end remove_from removed_lines total_lines \u003c \"$tmp_meta\"\n\n echo \"NEEDS ARCHIVE: $file ($total_lines lines > $limit)\"\n echo \" - Completed/Done header at line: $completed_header_line\"\n echo \" - Section range: $section_start..$section_end\"\n echo \" - Would remove: $remove_from..$section_end ($removed_lines lines)\"\n\n if [[ \"$mode\" != \"fix\" ]]; then\n rm -f \"$tmp_meta\" \"$tmp_removed\" \"$tmp_new\"\n return 0\n fi\n\n local ym today base archive_file\n ym=\"$(date +%Y-%m)\"\n today=\"$(date +%Y-%m-%d)\"\n base=\"$(basename \"$file\" .md)\"\n archive_file=\"$skill_dir/docs/archives/${base}-${ym}.md\"\n\n # Extract removed region into tmp_removed.\n awk -v from=\"$remove_from\" -v to=\"$section_end\" 'NR>=from && NR\u003c=to { print }' \"$file\" > \"$tmp_removed\"\n\n # Build new file to tmp_new (exclude removed region).\n awk -v from=\"$remove_from\" -v to=\"$section_end\" 'NR\u003cfrom || NR>to { print }' \"$file\" > \"$tmp_new\"\n\n if [[ \"$dry_run\" == \"true\" ]]; then\n echo \"DRY RUN: would append to $archive_file and rewrite $file\"\n rm -f \"$tmp_meta\" \"$tmp_removed\" \"$tmp_new\"\n return 0\n fi\n\n if [[ \"$backup\" == \"true\" ]]; then\n cp \"$file\" \"${file}.bak\"\n fi\n\n if [[ ! -f \"$archive_file\" ]]; then\n {\n echo \"# ${base} Archive — ${ym}\"\n echo\n } > \"$archive_file\"\n fi\n\n {\n echo\n echo \"## Archived from ${base}.md on ${today}\"\n echo\n cat \"$tmp_removed\"\n echo\n } >> \"$archive_file\"\n\n mv \"$tmp_new\" \"$file\"\n\n rm -f \"$tmp_meta\" \"$tmp_removed\"\n echo \"ARCHIVED: $file -> $archive_file\"\n}\n\nprocess_file \"$skill_dir/ROADMAP.md\"\nprocess_file \"$skill_dir/PROGRESS.md\"\n\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":5940,"content_sha256":"ef5ab8c2b4d1e14bae5cabbca0097a541be34ce012b36dac14a333510f747487"},{"filename":"scripts/detect-agent-context","content":"#!/usr/bin/env bash\nset -euo pipefail\n\nscript_dir=\"$(cd -- \"$(dirname -- \"${BASH_SOURCE[0]}\")\" && pwd)\"\n\ndetect_shell() {\n local uname_s term_program\n uname_s=\"$(uname -s 2>/dev/null || echo unknown)\"\n term_program=\"${TERM_PROGRAM:-}\"\n\n if [[ -n \"${WSL_DISTRO_NAME:-}\" ]] || grep -qi microsoft /proc/version 2>/dev/null; then\n echo \"wsl\"\n return 0\n fi\n\n case \"$uname_s\" in\n MINGW*|MSYS*|CYGWIN*) echo \"git-bash\"; return 0 ;;\n Darwin*)\n case \"$term_program\" in\n iTerm.app) echo \"macos-iterm\"; return 0 ;;\n Apple_Terminal) echo \"macos-terminal\"; return 0 ;;\n *) echo \"macos\"; return 0 ;;\n esac\n ;;\n Linux*) echo \"linux\"; return 0 ;;\n *) echo \"unknown\"; return 0 ;;\n esac\n}\n\ndetected=\"$(detect_shell)\"\ncase \"$detected\" in\n macos-iterm) echo \"Detected shell: iTerm (macOS)\" ;;\n macos-terminal) echo \"Detected shell: Terminal.app (macOS)\" ;;\n macos) echo \"Detected shell: macOS (unknown terminal)\" ;;\n linux) echo \"Detected shell: Linux\" ;;\n wsl) echo \"Detected shell: WSL\" ;;\n git-bash) echo \"Detected shell: Git Bash / MSYS\" ;;\n *) echo \"Detected shell: unknown\" ;;\nesac\n\n# Prefer PowerShell (pwsh) on Windows-ish environments when available.\nif [[ \"$detected\" == \"git-bash\" ]] && command -v pwsh >/dev/null 2>&1; then\n echo \"Using: PowerShell (pwsh) implementation\"\n exec pwsh -NoProfile -ExecutionPolicy Bypass -File \"$script_dir/detect-agent-context.ps1\" \"$@\"\nfi\n\necho \"Using: bash implementation\"\nexec bash \"$script_dir/detect-agent-context.sh\" \"$@\"\n","content_type":"text/plain; charset=utf-8","language":null,"size":1521,"content_sha256":"cda7dcc1999f31827d736d7a79d269460c18ccaf42edf54f71665acab5cacd4c"},{"filename":"scripts/detect-agent-context.sh","content":"#!/usr/bin/env bash\nset -euo pipefail\n\nroot=\".\"\ndeclare -a extra_mcp_paths\n\nusage() {\n cat \u003c\u003c'EOF'\nUsage:\n bash skills/agents-md-generator/scripts/detect-agent-context.sh [options]\n\nOptions:\n --root \u003cpath> Project root (default: .)\n --mcp-path \u003cpath> Additional MCP config path (repeatable)\n -h, --help Show help\n\nNotes:\n - This script reports presence of AI tool instruction files and MCP configs.\n - It does not print file contents, only paths and MCP server names.\nEOF\n}\n\nwhile [[ $# -gt 0 ]]; do\n case \"$1\" in\n --root) root=\"${2:?}\"; shift 2 ;;\n --mcp-path) extra_mcp_paths+=(\"${2:?}\"); shift 2 ;;\n -h|--help) usage; exit 0 ;;\n *) echo \"Unknown arg: $1\" >&2; usage >&2; exit 2 ;;\n esac\ndone\n\nroot=\"$(cd -- \"$root\" && pwd)\"\nhome_dir=\"${HOME:-}\"\ncodex_home=\"${CODEX_HOME:-}\"\nif [[ -z \"$codex_home\" && -n \"$home_dir\" ]]; then\n codex_home=\"$home_dir/.codex\"\nfi\n\nprint_header() {\n echo \"Agent Context Report\"\n echo \"Project root: $root\"\n echo\n}\n\nprint_section() {\n echo \"$1\"\n echo \"$(printf '%*s' ${#1} '' | tr ' ' '-')\"\n}\n\nreport_file() {\n local label=\"$1\"\n local path=\"$2\"\n if [[ -f \"$path\" ]]; then\n echo \"- $label: $path\"\n return 0\n fi\n return 1\n}\n\nreport_dir() {\n local label=\"$1\"\n local path=\"$2\"\n if [[ -d \"$path\" ]]; then\n echo \"- $label: $path\"\n return 0\n fi\n return 1\n}\n\nlist_glob_files() {\n local label=\"$1\"\n local glob=\"$2\"\n local found=\"false\"\n local matches=()\n\n while IFS= read -r match; do\n matches+=(\"$match\")\n done \u003c \u003c(compgen -G \"$glob\")\n\n if [[ ${#matches[@]} -gt 0 ]]; then\n for item in \"${matches[@]}\"; do\n if [[ -e \"$item\" ]]; then\n echo \"- $label: $item\"\n found=\"true\"\n fi\n done\n fi\n\n [[ \"$found\" == \"true\" ]]\n}\n\nlist_mcp_servers() {\n local file=\"$1\"\n if command -v python3 >/dev/null 2>&1; then\n python3 - \"$file\" \u003c\u003c'PY'\nimport json\nimport sys\n\npath = sys.argv[1]\ntry:\n with open(path, \"r\", encoding=\"utf-8\") as handle:\n data = json.load(handle)\nexcept Exception as exc:\n print(f\" - ERROR: {exc.__class__.__name__}\")\n sys.exit(0)\n\nservers = data.get(\"mcpServers\")\nif isinstance(servers, dict) and servers:\n for name in sorted(servers.keys()):\n print(f\" - {name}\")\nelse:\n print(\" - (no mcpServers found)\")\nPY\n return 0\n fi\n\n if command -v node >/dev/null 2>&1; then\n node -e \"const fs=require('fs');const p=process.argv[1];try{const data=JSON.parse(fs.readFileSync(p,'utf8'));const servers=data.mcpServers||{};const names=Object.keys(servers);if(names.length){names.sort().forEach(n=>console.log(' - '+n));}else{console.log(' - (no mcpServers found)');}}catch(e){console.log(' - ERROR: '+e.name);}\" \"$file\"\n return 0\n fi\n\n echo \" - (unable to parse; install python3 or node)\"\n}\n\nprint_header\n\nprint_section \"Project Instruction Files\"\n\nreport_file \"CLAUDE.md\" \"$root/CLAUDE.md\" || true\nreport_file \"AGENTS.override.md\" \"$root/AGENTS.override.md\" || true\nreport_file \"AGENTS.md\" \"$root/AGENTS.md\" || true\nreport_file \"GitHub Copilot\" \"$root/.github/copilot-instructions.md\" || true\nreport_file \"Cursor\" \"$root/.cursorrules\" || true\nreport_file \"Cline (.clinerules file)\" \"$root/.clinerules\" || true\nreport_dir \"Cline (.clinerules dir)\" \"$root/.clinerules\" || true\nreport_file \"Kilo Code (.kilocoderules)\" \"$root/.kilocoderules\" || true\nreport_dir \"Kilo Code (.kilo dir)\" \"$root/.kilo\" || true\nreport_file \"Kilo Code (.kilocodemodes)\" \"$root/.kilocodemodes\" || true\nreport_file \"Kilo Code (.kilocode/config.json)\" \"$root/.kilocode/config.json\" || true\nreport_dir \"Roo Code (.roo/rules)\" \"$root/.roo/rules\" || true\nlist_glob_files \"Roo Code (.roo/rules-*)\" \"$root/.roo/rules-*\" || true\nlist_glob_files \"Roo Code (.roorules*)\" \"$root/.roorules*\" || true\nreport_file \"OpenCode (opencode.jsonc)\" \"$root/opencode.jsonc\" || true\n\nif [[ -n \"${OPENCODE_CONFIG:-}\" ]]; then\n report_file \"OpenCode (OPENCODE_CONFIG)\" \"$OPENCODE_CONFIG\" || true\nfi\n\nreport_file \"Claude Code (repo prompt)\" \"$root/.claude/CLAUDE.md\" || true\nreport_file \"Claude Code (.mcp.json)\" \"$root/.mcp.json\" || true\n\necho\nprint_section \"Global Instruction Files\"\n\nif [[ -n \"$home_dir\" ]]; then\n report_file \"Claude Code Global Prompt\" \"$home_dir/.claude/CLAUDE.md\" || true\n report_dir \"Roo Code Global Rules\" \"$home_dir/.roo/rules\" || true\n list_glob_files \"Roo Code Global Rules (modes)\" \"$home_dir/.roo/rules-*\" || true\n report_dir \"Kilo Code Global Rules\" \"$home_dir/.kilocode/rules\" || true\nfi\n\nif [[ -n \"$codex_home\" ]]; then\n report_file \"Codex Global Override\" \"$codex_home/AGENTS.override.md\" || true\n report_file \"Codex Global Instructions\" \"$codex_home/AGENTS.md\" || true\n report_file \"Codex Config\" \"$codex_home/config.toml\" || true\nfi\n\necho\nprint_section \"MCP Configs\"\n\ndeclare -a mcp_candidates\nmcp_candidates+=(\"$root/.mcp.json\")\nmcp_candidates+=(\"$root/.roo/mcp.json\")\nmcp_candidates+=(\"$root/cline_mcp_settings.json\")\nif [[ -n \"$home_dir\" ]]; then\n mcp_candidates+=(\"$home_dir/.roo/mcp_settings.json\")\n mcp_candidates+=(\"$home_dir/.cline/cline_mcp_settings.json\")\n mcp_candidates+=(\"$home_dir/.config/cline/cline_mcp_settings.json\")\nfi\n\nif [[ ${#extra_mcp_paths[@]} -gt 0 ]]; then\n mcp_candidates+=(\"${extra_mcp_paths[@]}\")\nfi\n\nfound_any_mcp=\"false\"\nfor mcp_path in \"${mcp_candidates[@]}\"; do\n if [[ -f \"$mcp_path\" ]]; then\n found_any_mcp=\"true\"\n echo \"- $mcp_path\"\n list_mcp_servers \"$mcp_path\"\n fi\ndone\n\nif [[ \"$found_any_mcp\" == \"false\" ]]; then\n echo \"- (no MCP configs found)\"\nfi\n\necho\nprint_section \"Notes\"\necho \"- Global instructions and override files can affect project rules. Review them for conflicts.\"\necho \"- Use --mcp-path \u003cpath> to scan additional MCP config locations.\"\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":5669,"content_sha256":"8915a502cc9da3275cdf6426aa1998e7d7952eb3a207c00ebea1d5707607e66a"},{"filename":"scripts/scan-skill-duplicates","content":"#!/usr/bin/env bash\nset -euo pipefail\n\nscript_dir=\"$(cd -- \"$(dirname -- \"${BASH_SOURCE[0]}\")\" && pwd)\"\n\ndetect_shell() {\n local uname_s term_program\n uname_s=\"$(uname -s 2>/dev/null || echo unknown)\"\n term_program=\"${TERM_PROGRAM:-}\"\n\n if [[ -n \"${WSL_DISTRO_NAME:-}\" ]] || grep -qi microsoft /proc/version 2>/dev/null; then\n echo \"wsl\"\n return 0\n fi\n\n case \"$uname_s\" in\n MINGW*|MSYS*|CYGWIN*) echo \"git-bash\"; return 0 ;;\n Darwin*)\n case \"$term_program\" in\n iTerm.app) echo \"macos-iterm\"; return 0 ;;\n Apple_Terminal) echo \"macos-terminal\"; return 0 ;;\n *) echo \"macos\"; return 0 ;;\n esac\n ;;\n Linux*) echo \"linux\"; return 0 ;;\n *) echo \"unknown\"; return 0 ;;\n esac\n}\n\ndetected=\"$(detect_shell)\"\ncase \"$detected\" in\n macos-iterm) echo \"Detected shell: iTerm (macOS)\" ;;\n macos-terminal) echo \"Detected shell: Terminal.app (macOS)\" ;;\n macos) echo \"Detected shell: macOS (unknown terminal)\" ;;\n linux) echo \"Detected shell: Linux\" ;;\n wsl) echo \"Detected shell: WSL\" ;;\n git-bash) echo \"Detected shell: Git Bash / MSYS\" ;;\n *) echo \"Detected shell: unknown\" ;;\nesac\n\n# Prefer PowerShell (pwsh) on Windows-ish environments when available.\nif [[ \"$detected\" == \"git-bash\" ]] && command -v pwsh >/dev/null 2>&1; then\n echo \"Using: PowerShell (pwsh) implementation\"\n exec pwsh -NoProfile -ExecutionPolicy Bypass -File \"$script_dir/scan-skill-duplicates.ps1\" \"$@\"\nfi\n\necho \"Using: bash implementation\"\nexec bash \"$script_dir/scan-skill-duplicates.sh\" \"$@\"\n","content_type":"text/plain; charset=utf-8","language":null,"size":1523,"content_sha256":"31c8dad8b36a78eb159eb74dd2f2481ecb99e1e1e8256d71966743f8e187f77b"},{"filename":"scripts/scan-skill-duplicates.sh","content":"#!/usr/bin/env bash\nset -euo pipefail\n\nskills_dir=\"skills\"\n\nusage() {\n cat \u003c\u003c'EOF'\nUsage:\n bash skills/agents-md-generator/scripts/scan-skill-duplicates.sh [options]\n\nOptions:\n --skills-dir \u003cpath> Skills directory (default: skills)\n -h, --help Show help\n\nNotes:\n - Computes a combined hash of each skill folder (file paths + contents).\n - Reports duplicate skill folders and suggests choosing one canonical source.\nEOF\n}\n\nwhile [[ $# -gt 0 ]]; do\n case \"$1\" in\n --skills-dir) skills_dir=\"${2:?}\"; shift 2 ;;\n -h|--help) usage; exit 0 ;;\n *) echo \"Unknown arg: $1\" >&2; usage >&2; exit 2 ;;\n esac\ndone\n\nskills_dir=\"$(cd -- \"$skills_dir\" && pwd)\"\nhash_index=\"$(mktemp)\"\nsorted_index=\"$(mktemp)\"\ntrap 'rm -f \"$hash_index\" \"$sorted_index\"' EXIT\n\nhash_file() {\n local file=\"$1\"\n if command -v shasum >/dev/null 2>&1; then\n shasum -a 256 \"$file\" | awk '{print $1}'\n return 0\n fi\n if command -v sha256sum >/dev/null 2>&1; then\n sha256sum \"$file\" | awk '{print $1}'\n return 0\n fi\n echo \"ERROR: missing shasum/sha256sum\" >&2\n exit 1\n}\n\necho \"Skill Duplicate Scan\"\necho \"Skills root: $skills_dir\"\necho\n\nfound_skill=\"false\"\nfor dir in \"$skills_dir\"/*; do\n [[ -d \"$dir\" ]] || continue\n if [[ ! -f \"$dir/SKILL.md\" ]]; then\n continue\n fi\n found_skill=\"true\"\n\n tmp_file=\"$(mktemp)\"\n while IFS= read -r file; do\n rel_path=\"${file#$dir/}\"\n file_hash=\"$(hash_file \"$file\")\"\n printf \"%s %s\\n\" \"$file_hash\" \"$rel_path\" >> \"$tmp_file\"\n done \u003c \u003c(find \"$dir\" -type f ! -path \"*/docs/archives/*\" ! -path \"*/.git/*\" ! -name \".DS_Store\" | sort)\n\n combined_hash=\"$(hash_file \"$tmp_file\")\"\n rm -f \"$tmp_file\"\n printf \"%s\\t%s\\n\" \"$combined_hash\" \"$dir\" >> \"$hash_index\"\ndone\n\nif [[ \"$found_skill\" == \"false\" ]]; then\n echo \"No skills found. Expected subfolders with SKILL.md.\"\n exit 0\nfi\n\nduplicate_found=\"false\"\nprint_group() {\n local hash=\"$1\"\n shift\n local dirs=(\"$@\")\n\n if (( ${#dirs[@]} > 1 )); then\n duplicate_found=\"true\"\n echo \"Duplicate group: $hash\"\n for dup_dir in \"${dirs[@]}\"; do\n echo \" - $dup_dir\"\n done\n canonical=\"${dirs[0]}\"\n echo \" Suggested canonical source: $canonical\"\n echo \" Merge any unique content into the canonical folder, then remove or regroup duplicates.\"\n echo\n fi\n}\n\nsort -k1,1 \"$hash_index\" > \"$sorted_index\"\n\ncurrent_hash=\"\"\ncurrent_dirs=()\nwhile IFS=

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\\t' read -r hash dir; do\n if [[ -z \"$current_hash\" ]]; then\n current_hash=\"$hash\"\n current_dirs=(\"$dir\")\n continue\n fi\n\n if [[ \"$hash\" == \"$current_hash\" ]]; then\n current_dirs+=(\"$dir\")\n else\n print_group \"$current_hash\" \"${current_dirs[@]}\"\n current_hash=\"$hash\"\n current_dirs=(\"$dir\")\n fi\ndone \u003c \"$sorted_index\"\n\nif [[ -n \"$current_hash\" ]]; then\n print_group \"$current_hash\" \"${current_dirs[@]}\"\nfi\n\nif [[ \"$duplicate_found\" == \"false\" ]]; then\n echo \"No duplicate skills found.\"\nfi\n\necho \"Notes:\"\necho \"- Avoid symlink-based consolidation; some agent scanners may count both paths as separate context.\"\necho \"- If duplicates are generated under plugins/, edit skills/ and run npm run sync instead.\"\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":3100,"content_sha256":"88ffa1fd92b233e30a74b1b5409b33afae9f07880e9c4329c99d7a20d848c9f2"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"AGENTS.md / CLAUDE.md Generator","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill helps you generate comprehensive instruction files (AGENTS.md with optional CLAUDE.md compatibility) that teach AI coding agents how to work effectively in your project. It combines automatic project scanning with interactive questions to create tailored guidelines.","type":"text"}]},{"type":"paragraph","content":[{"text":"When to use this skill:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Setting up a new project for AI-assisted development","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Updating existing instruction files after project changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Standardizing AI agent behavior across team members","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migrating from one AI tool to another","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Key Principle","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not duplicate specialized skills.","type":"text","marks":[{"type":"strong"}]},{"text":" If a request falls into a specialized domain (e.g., Design System), delegate to the specialized skill when available.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use ","type":"text","marks":[{"type":"strong"}]},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" as the shared project manual.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" is plain Markdown with no required fields. Cover the details an agent needs to work effectively: project overview, build and test commands, code style, testing expectations, security notes, PR/commit rules, and deployment gotchas.","type":"text"}]},{"type":"paragraph","content":[{"text":"Handle ","type":"text","marks":[{"type":"strong"}]},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" as a Codex-specific override, not the default.","type":"text","marks":[{"type":"strong"}]},{"text":" Codex checks ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" before ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" at both global and project-directory scopes, and includes at most one instruction file per directory. If both files exist in the same directory, Codex uses ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ignores that directory's ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". Create or update ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when the user explicitly wants a Codex-specific or nested-directory override.","type":"text"}]},{"type":"paragraph","content":[{"text":"Respect Codex instruction discovery.","type":"text","marks":[{"type":"strong"}]},{"text":" Codex builds its instruction chain once per run/session: global instructions first, then project files from repository root down to the current working directory. The global Codex directory defaults to ","type":"text"},{"text":"~/.codex","type":"text","marks":[{"type":"code_inline"}]},{"text":" and can be changed with ","type":"text"},{"text":"CODEX_HOME","type":"text","marks":[{"type":"code_inline"}]},{"text":". Files closer to the current directory appear later and override earlier guidance. Codex skips empty files and stops adding files when the combined size reaches ","type":"text"},{"text":"project_doc_max_bytes","type":"text","marks":[{"type":"code_inline"}]},{"text":" (32 KiB by default). If ","type":"text"},{"text":"~/.codex/config.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" defines ","type":"text"},{"text":"project_doc_fallback_filenames","type":"text","marks":[{"type":"code_inline"}]},{"text":", Codex checks those names after ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Use ","type":"text","marks":[{"type":"strong"}]},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" only as Claude Code compatibility by default.","type":"text","marks":[{"type":"strong"}]},{"text":" Claude Code reads ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", not ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" directly, so a shared setup needs a ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" file that imports ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Start","type":"text"}]},{"type":"paragraph","content":[{"text":"To generate a new AGENTS.md file:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Navigate to your project root","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tell the AI agent: \"Use the agents-md-generator skill to create an AGENTS.md file\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Answer the interactive questions about your project","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review and customize the generated file","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Answering Questions (Convenient Formats)","type":"text"}]},{"type":"paragraph","content":[{"text":"When this skill asks numbered questions with lettered options, users can answer in any style:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Short form (fast): ","type":"text"},{"text":"1a 2b 3c","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mixed form: ","type":"text"},{"text":"1a 2b 3c 4b (also scan packages/*) 5d","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Full sentences: “Use medium scan depth and Docker Compose; service name is app.”","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Short form is never required; it is only provided for convenience.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Generation Modes","type":"text"}]},{"type":"paragraph","content":[{"text":"Interactive Mode (Default):","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Guides you through each phase with questions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best for first-time setup or complex projects","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Maximum customization","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Quick Mode:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tell the AI: \"Generate AGENTS.md in quick mode\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skips all questions, uses auto-detection only","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best for experienced users or simple projects","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Uses Medium scan depth by default","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generates all standard sections based on detection","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Interactive Workflow","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 1: Initialization & Discovery","type":"text"}]},{"type":"paragraph","content":[{"text":"Check for existing files:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Look for ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the project root.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists, ask user: \"I found an existing AGENTS.md. Would you like to:\"","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update it (merge new content while preserving customizations)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Replace it (generate fresh, backup existing)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cancel","type":"text"}]}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reply examples (optional): ","type":"text"},{"text":"1","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"update","type":"text","marks":[{"type":"code_inline"}]},{"text":"; ","type":"text"},{"text":"2","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"replace","type":"text","marks":[{"type":"code_inline"}]},{"text":"; ","type":"text"},{"text":"3","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"cancel","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists but ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" does not, ask user before changing it:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migrate to ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the primary file and replace ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" with a compatibility reference to ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" side by side with separate instructions for different AI agents","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cancel","type":"text"}]}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reply examples (optional): ","type":"text"},{"text":"1","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"migrate","type":"text","marks":[{"type":"code_inline"}]},{"text":"; ","type":"text"},{"text":"2","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"keep both","type":"text","marks":[{"type":"code_inline"}]},{"text":"; ","type":"text"},{"text":"3","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"cancel","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If both ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" exist, ask whether ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" should become the single source of truth with ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" referencing it, or whether the user intentionally wants both files to remain independent.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists, explain that Codex gives it priority over ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" in that directory. Ask whether to update the override, merge it back into ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", or leave it as a Codex-specific override.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Determine primary file:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Default: ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as primary source of truth.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" is not the primary file. Use it only for Codex-specific overrides, temporary overrides, or nested directory rules that should supersede broader ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" guidance for Codex.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a secondary compatibility file for Claude Code, because Claude Code reads ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" rather than ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" directly. Do not use symbolic links; some AI agents may read both files and duplicate context.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When sharing the same instructions with Claude Code, make ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" a normal text file whose first line is:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"@AGENTS.md","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Additional Claude-specific instructions may be added below the import only when the user explicitly wants them.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the project already has a meaningful ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ask the user before replacing it. The user may prefer to keep both files with different guidance for different AI tools.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 1b: Agent Tooling & System Prompt Alignment (Scripted)","type":"text"}]},{"type":"paragraph","content":[{"text":"Goal:","type":"text","marks":[{"type":"strong"}]},{"text":" Detect AI tool instruction files, global system prompts, and MCP configs using scripts (not AI scanning) to save tokens and avoid missing overrides.","type":"text"}]},{"type":"paragraph","content":[{"text":"Run the detection script (best effort):","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"bash/zsh: ","type":"text"},{"text":"bash skills/agents-md-generator/scripts/detect-agent-context --root .","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Windows cmd: ","type":"text"},{"text":"skills\\agents-md-generator\\scripts\\detect-agent-context.cmd --root .","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"The script should report:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Project instruction files for AI tools (Copilot, Cursor, Cline, Kilo Code, Roo Code, OpenCode, Codex, Claude Code)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Global instruction files (e.g., ","type":"text"},{"text":"~/.claude/CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~/.codex/AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~/.codex/AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~/.codex/config.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~/.roo/rules/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~/.kilocode/rules/","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP config files and server names (from ","type":"text"},{"text":".mcp.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".roo/mcp.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"mcp_settings.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", plus any ","type":"text"},{"text":"--mcp-path","type":"text","marks":[{"type":"code_inline"}]},{"text":" entries)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If script is unavailable:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do a minimal manual check using the paths listed in ","type":"text"},{"text":"references/tech-stack-detection.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" under ","type":"text"},{"text":"AI Agent Tooling Detection","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Warn the user about overrides:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"~/.claude/CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" or other global instruction files exist, explicitly warn that they can override project prompts.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask the user to review or adjust those system prompts to avoid conflicts with this repo.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Ask the user to confirm tool usage:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"I detected these AI tool instruction sources:\n- .github/copilot-instructions.md (GitHub Copilot)\n- .cursorrules (Cursor)\n- .clinerules or .clinerules/ (Cline)\n- .kilocoderules / .kilo/ / .kilocodemodes (Kilo Code)\n- .roo/rules/ / .roo/rules-* / .roorules* (Roo Code)\n- opencode.jsonc (OpenCode)\n- AGENTS.override.md / AGENTS.md (Codex project instructions)\n- ~/.codex/AGENTS.override.md / ~/.codex/AGENTS.md / ~/.codex/config.toml (Codex global instructions and config)\n- .claude/CLAUDE.md or ~/.claude/CLAUDE.md (Claude Code)\n\nWhich of these do you actively use for this project, and should we align or ignore any of them?","type":"text"}]},{"type":"paragraph","content":[{"text":"If MCP servers are detected:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask whether they should be used in this project.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Capture a short purpose/usage note for each server.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 1c: Skill Library Duplicate Scan (Scripted)","type":"text"}]},{"type":"paragraph","content":[{"text":"If a ","type":"text"},{"text":"skills/","type":"text","marks":[{"type":"code_inline"}]},{"text":" folder exists, run the duplicate scan script to avoid copy-pasted skills:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"bash/zsh: ","type":"text"},{"text":"bash skills/agents-md-generator/scripts/scan-skill-duplicates --skills-dir skills","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Windows cmd: ","type":"text"},{"text":"skills\\agents-md-generator\\scripts\\scan-skill-duplicates.cmd --skills-dir skills","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"If duplicates are detected:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommend choosing one canonical folder under ","type":"text"},{"text":"skills/","type":"text","marks":[{"type":"code_inline"}]},{"text":" and merging any unique content into it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not recommend symbolic links for duplicate skill folders; agent scanners may count both paths as separate context.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a duplicate only exists under ","type":"text"},{"text":"plugins/\u003cplugin-name>/skills/","type":"text","marks":[{"type":"code_inline"}]},{"text":", treat it as a generated package copy. Edit the source under ","type":"text"},{"text":"skills/","type":"text","marks":[{"type":"code_inline"}]},{"text":" and run ","type":"text"},{"text":"npm run sync","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 2: Scan Depth Selection","type":"text"}]},{"type":"paragraph","content":[{"text":"Ask the user:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"What scan depth should I use to analyze your project?\n\n1. Quick (approximately 30 seconds)\n Scans: package.json, composer.json, docker-compose.yml, pyproject.toml,\n Gemfile, go.mod, Cargo.toml, and other root config files\n Best for: When you know your stack well and want fast generation\n\n2. Medium (approximately 1-2 minutes) [RECOMMENDED]\n Scans: Root configs + src/, app/, lib/, config/, routes/, components/,\n pages/, views/, controllers/, models/, services/\n Best for: Most projects - good balance of accuracy and speed\n\n3. Deep (approximately 3-5 minutes)\n Scans: Entire project tree including tests/, docs/, scripts/, all\n subdirectories, hidden configs, and build artifacts\n Best for: Complex projects, monorepos, or unfamiliar codebases\n\nReply examples:\n- Short: `2` (or `1` / `3`)\n- With extra notes: `2 (also scan packages/*)`","type":"text"}]},{"type":"paragraph","content":[{"text":"Scan actions per depth:","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Depth","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Files Scanned","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Directories Explored","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Quick","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Root configs only","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"None (root level)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Medium","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Configs + source headers","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"src/, app/, lib/, config/, routes/","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Deep","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"All files","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Full tree traversal","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 3: Environment Detection","type":"text"}]},{"type":"paragraph","content":[{"text":"Ask the user:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"What development environment does this project use?\n\n1. Docker Compose\n - Commands run via: docker compose exec \u003cservice> \u003ccommand>\n - Example: docker compose exec app php artisan migrate\n\n2. Laravel Sail\n - Commands run via: ./vendor/bin/sail \u003ccommand>\n - Example: ./vendor/bin/sail artisan migrate\n\n3. Native/Host Machine\n - Commands run directly on your machine\n - Example: php artisan migrate\n\n4. Dev Containers / Codespaces\n - Commands run inside the container environment\n\n5. Other (please describe)\n - Specify your custom environment setup\n\nReply examples:\n- Short: `1` (or `2` / `3` / `4` / `5`)\n- Detailed: `1; main service is app; node runs in node service`","type":"text"}]},{"type":"paragraph","content":[{"text":"Follow-up questions based on selection:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Docker: \"What is the main service name? (e.g., app, web, php)\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Docker: \"Do you have separate services for different runtimes? (e.g., app for PHP, node for JS)\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Native: \"Do you use any version managers? (nvm, rbenv, pyenv, etc.)\"","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 4: Auto-Detection + Confirmation","type":"text"}]},{"type":"paragraph","content":[{"text":"Scan the project based on selected depth and detect:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Backend Framework:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Laravel (composer.json + artisan)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Express/Node (package.json + server files)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Django/Flask (requirements.txt + manage.py/app.py)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rails (Gemfile + config/routes.rb)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Spring Boot (pom.xml/build.gradle + @SpringBootApplication)","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Frontend Framework:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Vue.js (package.json + .vue files)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"React (package.json + .jsx/.tsx files)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Angular (angular.json)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Svelte (svelte.config.js)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Next.js/Nuxt.js (next.config.js/nuxt.config.ts)","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Package Manager:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"npm/yarn/pnpm/bun (package-lock.json/yarn.lock/pnpm-lock.yaml/bun.lockb)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Composer (composer.lock)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"pip/poetry (requirements.txt/poetry.lock)","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Testing Framework:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"PHPUnit (phpunit.xml)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pest (pestphp/pest in composer.json)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Jest (jest.config.js)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Vitest (vitest.config.ts)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"pytest (pytest.ini/conftest.py)","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code Style/Linting:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Laravel Pint (pint.json)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint (.eslintrc.*)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prettier (.prettierrc.*)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"PHP CS Fixer (.php-cs-fixer.php)","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Database:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MySQL/MariaDB (config references)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"PostgreSQL (config references)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"SQLite (database/*.sqlite)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MongoDB (mongoose in package.json)","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AI Agent Tooling (scripted detection):","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Copilot (","type":"text"},{"text":".github/copilot-instructions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cursor (","type":"text"},{"text":".cursorrules","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cline (","type":"text"},{"text":".clinerules","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":".clinerules/","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Kilo Code (","type":"text"},{"text":".kilocoderules","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".kilo/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".kilocodemodes","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".kilocode/config.json","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Roo Code (","type":"text"},{"text":".roo/rules/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".roo/rules-*","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".roorules*","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".roo/mcp.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"mcp_settings.json","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"OpenCode (","type":"text"},{"text":"opencode.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"OPENCODE_CONFIG","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Codex (","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~/.codex/AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~/.codex/AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~/.codex/config.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Claude Code (","type":"text"},{"text":".claude/CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"~/.claude/CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".mcp.json","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Present findings to user:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"I detected the following tech stack:\n\nBackend:\n - Laravel 11 (high confidence)\n - PHP 8.3 (from composer.json)\n\nFrontend:\n - Vue.js 3 with Composition API (high confidence)\n - TailwindCSS v3 (from package.json)\n\nTesting:\n - Pest PHP (from composer.json)\n - Vitest (from package.json)\n\nCode Style:\n - Laravel Pint (pint.json found)\n - ESLint + Prettier (configs found)\n\nEnvironment:\n - Docker Compose detected (docker-compose.yml)\n - Services: app, mysql, redis\n\nIs this correct? Would you like to add or modify anything?","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 4b: Optional Sections (Interactive Mode Only)","type":"text"}]},{"type":"paragraph","content":[{"text":"Ask the user about optional sections:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Would you like to include any of these optional sections?\n\n1. CI/CD Configuration\n - Detect: GitHub Actions, GitLab CI, CircleCI, Jenkins\n - Include: Pipeline commands, deployment notes\n\n2. Git Workflow Guidelines\n - Include: Branch naming, commit message format, PR guidelines\n - Detect: .github/PULL_REQUEST_TEMPLATE.md, commitlint config\n\n3. Security Guidelines\n - Include: Env file handling, secrets management, input validation\n - Best practices for the detected stack\n\n4. API Documentation\n - Detect: OpenAPI/Swagger specs, Postman collections\n - Include: Documentation conventions and tooling\n\n5. Mobile App Guidelines (if detected)\n - React Native / Flutter specific patterns\n - Platform-specific considerations\n\n6. Monorepo Guidelines (if detected)\n - Nx / Turborepo / Lerna workspace patterns\n - Package management and dependencies\n\n7. System Prompt Alignment (if detected)\n - Document global or editor-level prompts that can override project rules\n - Remind contributors to review and align prompts\n\n8. MCP Servers & Tooling (if detected)\n - List MCP servers and when to use them\n - Include required environment variables or access notes\n\n9. Project Progress Memory (PROGRESS.md)\n - Ask if the team wants `PROGRESS.md` for continuity across tasks\n - Require an `Original Prompt` section so future runs can compare intent vs current status\n\nSelect the sections you need (comma-separated numbers, or 'none' to skip):\n\nReply examples:\n- Short: `none`\n- Multiple: `1,3,4`\n- With extra notes: `2,3,7 (also include branch naming rules)`","type":"text"}]},{"type":"paragraph","content":[{"text":"Note:","type":"text","marks":[{"type":"strong"}]},{"text":" In Quick Mode, these optional sections are skipped unless auto-detected with high confidence.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 5: Section Generation","type":"text"}]},{"type":"paragraph","content":[{"text":"Generate the following sections based on detected stack and user input:","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 1: Header & Role","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"# AI Agent Guidelines & Repository Manual\n\n**Role:** You are an expert Senior [DETECTED_ROLE] and Technical Lead.\nYou are responsible for the entire lifecycle of a task: understanding,\nplanning, [STACK_SPECIFIC_RESPONSIBILITIES].","type":"text"}]},{"type":"paragraph","content":[{"text":"Role detection rules:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Laravel only → \"Laravel Backend Engineer\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Vue/React only → \"[Framework] Frontend Engineer\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Laravel + Vue/React → \"Full-Stack Developer\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Node.js backend → \"Node.js Backend Engineer\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generic → \"Software Engineer\"","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 2: Auto-Pilot Workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"Generate the 6-step workflow cycle:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Discovery & Context","type":"text","marks":[{"type":"strong"}]},{"text":" - What to read first, where to find docs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Plan","type":"text","marks":[{"type":"strong"}]},{"text":" - How to break down tasks, constraints to check","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Documentation","type":"text","marks":[{"type":"strong"}]},{"text":" - When to update docs, what format to use","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implementation","type":"text","marks":[{"type":"strong"}]},{"text":" - Coding standards, patterns to follow","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verification & Refinement","type":"text","marks":[{"type":"strong"}]},{"text":" - Testing, linting, manual checks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Self-Review","type":"text","marks":[{"type":"strong"}]},{"text":" - Checklist of common mistakes to avoid","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Each step includes stack-specific instructions from templates.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 3: Documentation & Knowledge Base","type":"text"}]},{"type":"paragraph","content":[{"text":"List paths to important documentation:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Documentation & Knowledge Base\n\nYou are expected to read and adhere to these single sources of truth:\n\n* **[Doc Type]**: `[path/to/doc.md]` ([Brief description])","type":"text"}]},{"type":"paragraph","content":[{"text":"Auto-detect common paths:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"docs/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"documentation/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"CONTRIBUTING.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"docs/api/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"docs/architecture/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Important","type":"text","marks":[{"type":"strong"}]},{"text":": Do not list ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" in this section. These files are already loaded by AI tools, and self-references waste context.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For new docs, prefer YAML frontmatter + Markdown body (headings, tables, examples) so metadata and content stay consistent.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 4: Project Structure & Architecture","type":"text"}]},{"type":"paragraph","content":[{"text":"Map the folder structure with purposes:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Project Structure & Architecture\n\n* **`[folder/]`**: [Purpose description]","type":"text"}]},{"type":"paragraph","content":[{"text":"Common patterns to detect:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MVC structure (controllers, models, views)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Feature-based modules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Domain-driven design","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component-based frontend","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 5: Development Environment","type":"text"}]},{"type":"paragraph","content":[{"text":"Based on Phase 3 selection:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Development Environment\n\n### Container Commands (if Docker)\n* App container: `docker compose exec [service] \u003ccommand>`\n\n### Host Commands\n* Git, file operations, IDE commands\n\n### Key Commands\n* Format: `[detected formatter command]`\n* Test: `[detected test command]`\n* Build: `[detected build command]`","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 6: Coding Standards","type":"text"}]},{"type":"paragraph","content":[{"text":"Based on detected stack:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Coding Standards (The \"Gold Standard\")\n\n* **Language**: [Language] [Version]\n* **Framework**: [Framework] [Version]\n* **Code Style**: [Style guide/tool]\n* **Strictness**: [Type hints, strict mode, etc.]","type":"text"}]},{"type":"paragraph","content":[{"text":"Include anti-patterns section if applicable:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"### Critical Anti-Patterns\n- [Stack-specific anti-patterns to avoid]","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 7: Domain Specifics (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If the project has specific domain rules detected:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Domain Specifics & Non-Negotiables\n\n* **[Rule Category]**: [Rule description]","type":"text"}]},{"type":"paragraph","content":[{"text":"Common domain patterns:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Multi-tenant applications","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Permission/role systems","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Localization requirements","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Real-time features","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 8: CI/CD Configuration (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If user selected or auto-detected:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## CI/CD & Deployment\n\n### Detected Pipelines\n* **GitHub Actions**: `.github/workflows/`\n* **GitLab CI**: `.gitlab-ci.yml`\n\n### Pipeline Commands\n* Run tests: `[detected command]`\n* Build: `[detected command]`\n* Deploy: `[detected command]`\n\n### Deployment Notes\n* [Environment-specific notes]","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 9: Git Workflow (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If user selected:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Git Workflow\n\n### Branch Naming\n* Feature: `feature/\u003cticket>-\u003cdescription>`\n* Bugfix: `fix/\u003cticket>-\u003cdescription>`\n* Hotfix: `hotfix/\u003cdescription>`\n\n### Commit Message Format","type":"text"}]},{"type":"paragraph","content":[{"text":"type(scope): description","type":"text"}]},{"type":"paragraph","content":[{"text":"[optional body]","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`\n\n### Pull Request Guidelines\n* Reference ticket/issue in description\n* Ensure tests pass before requesting review\n* Keep PRs focused and reasonably sized","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 10: Security Guidelines (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If user selected:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Security Guidelines\n\n### Environment Variables\n* Never commit `.env` files (only `.env.example`)\n* Use secrets management for production\n* Rotate credentials regularly\n\n### Input Validation\n* Validate all user input at boundaries\n* Sanitize data before database queries\n* Use parameterized queries (ORM handles this)\n\n### Authentication & Authorization\n* [Stack-specific auth patterns]\n* Always verify permissions before actions","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 11: API Documentation (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If detected or user selected:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## API Documentation\n\n### Documentation Location\n* OpenAPI Spec: `[path/to/openapi.yaml]`\n* Postman Collection: `[path/to/collection.json]`\n\n### Documentation Standards\n* Keep API docs in sync with implementation\n* Document all endpoints, request/response schemas\n* Include example requests and responses","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 12: Mobile Guidelines (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If React Native or Flutter detected:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Mobile Development\n\n### Platform Considerations\n* Test on both iOS and Android\n* Handle platform-specific UI patterns\n* Consider offline functionality\n\n### Build Commands\n* iOS: `[build command]`\n* Android: `[build command]`","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 13: Monorepo Guidelines (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If monorepo detected:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Monorepo Structure\n\n### Workspace Management\n* Package manager: [pnpm/yarn/npm workspaces]\n* Build tool: [Nx/Turborepo/Lerna]\n\n### Package Dependencies\n* Use workspace protocol for internal packages\n* Keep shared dependencies at root level\n\n### Commands\n* Build all: `[command]`\n* Build affected: `[command]`\n* Test affected: `[command]`","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 14: System Prompt Alignment (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If global or editor-level prompts were detected or the user requests it:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## System Prompt Alignment\n\nThese prompts can override project instructions. Review and align them with this file:\n\n* **Claude Code Global Prompt**: `~/.claude/CLAUDE.md` (review for conflicts)\n* **GitHub Copilot**: `.github/copilot-instructions.md` (project scope)\n* **Cursor Rules**: `.cursorrules`\n* **Cline Rules**: `.clinerules` or `.clinerules/`\n* **Kilo Code Rules**: `.kilocoderules` / `.kilo/` / `.kilocodemodes`\n* **Roo Code Rules**: `.roo/rules/` / `.roo/rules-*` / `.roorules*`\n* **OpenCode Config**: `opencode.jsonc`\n* **Codex Project Instructions**: `AGENTS.override.md` / `AGENTS.md`\n* **Codex Global Instructions**: `~/.codex/AGENTS.override.md` / `~/.codex/AGENTS.md`\n* **Codex Config**: `~/.codex/config.toml`\n\nIf any of these conflict with this file, update the global/system prompts first.\n\n### Local AI Tool Folders & Git Hygiene\nRemind contributors to keep local AI tool data out of Git:\n\n* Add local folders like `.codex/` and `.claude/` to `.gitignore` because they may contain sensitive prompts, logs, or secrets.\n* Put shareable skill packs in `.agents/skills/` so teams can version and share them safely.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 15: MCP Servers & Tooling (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If MCP servers are detected and user opts in:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## MCP Servers & Tooling\n\nUse these MCP servers when the task matches their capability:\n\n* **[server-name]**: [Purpose, when to use it, required env vars]\n\nIf a server is not needed for this project, disable it in the MCP config.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Section 16: Project Progress Memory (PROGRESS.md) (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"If the user wants project progress tracking:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Project Progress Tracking\n\nUse one lightweight progress file that all agents can continue from:\n\n* **Progress**: `PROGRESS.md` (current focus + recent completions)\n* **Required field**: `Original Prompt` (copy exact user request that started the task)\n\nAt the start of every task, read `PROGRESS.md` first, compare with the active request, and continue unfinished work before starting unrelated changes.\n\nIf a memory MCP server is used instead, keep `PROGRESS.md` minimal or omit it.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 6: File Creation/Update","type":"text"}]},{"type":"paragraph","content":[{"text":"For new files:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Write ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" with generated content.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as a normal text file for Claude Code compatibility. The first line must be:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"@AGENTS.md","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not create a symbolic link between ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". Claude Code supports symlinks, but this skill intentionally uses the ","type":"text"},{"text":"@AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" import to avoid duplicate-context behavior in other agents.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the user wants Claude-specific rules, add them below the ","type":"text"},{"text":"@AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" import under a ","type":"text"},{"text":"## Claude Code","type":"text","marks":[{"type":"code_inline"}]},{"text":" heading.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not create ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" by default. Create it only when the user asks for Codex-specific override behavior.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If ","type":"text","marks":[{"type":"strong"}]},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" exists or is requested:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Treat it as a Codex-only override with higher precedence than ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the same directory.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If it exists beside ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", warn that Codex ignores that directory's ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and reads the override instead.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For specialized subprojects, place ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as close as possible to the files it should govern.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep override content narrow; common instructions should remain in ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the project uses ","type":"text"},{"text":"project_doc_fallback_filenames","type":"text","marks":[{"type":"code_inline"}]},{"text":", mention that fallback files are checked only after ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If an existing ","type":"text","marks":[{"type":"strong"}]},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is present without ","type":"text","marks":[{"type":"strong"}]},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":":","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask the user whether to migrate or keep both files.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If migrating:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Back up the existing ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Move or merge its useful guidance into ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Replace ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" with a normal text file starting with ","type":"text"},{"text":"@AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If keeping both:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Treat ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as intentionally separate instruction files.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask which guidance belongs in each file before editing.","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"For updates (merge mode):","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Parse the primary existing file (","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" by default) into sections (split by ","type":"text"},{"text":"## ","type":"text","marks":[{"type":"code_inline"}]},{"text":" headers)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Compare auto-detected findings against existing guidance; if they conflict, ask the user whether to keep existing content, replace it, or merge.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each section:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If exists in both: Show diff and ask user preference","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If only in existing: Preserve (user customization)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If only in new: Add with note","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate merged file","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Show summary of changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ensure the generated ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" content does not instruct the agent to read ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", since those files are already loaded by AI tools.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Design System Delegation (Skill Reuse Policy)","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill is intentionally ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" a full Design System engine. When the user requests any of the following:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"design system\", \"UI consistency\", \"style guide\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"colors/typography/tokens\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"component library rules\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"generate DESIGN_SYSTEM.md\"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Then this skill must:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If ","type":"text"},{"text":"design-system-generator","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill is available:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Delegate","type":"text","marks":[{"type":"strong"}]},{"text":" generation of ","type":"text"},{"text":"DESIGN_SYSTEM.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" to ","type":"text"},{"text":"design-system-generator","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Then update ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" to reference ","type":"text"},{"text":"DESIGN_SYSTEM.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" with this block:","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Design System\nAll UI components and pages must follow `DESIGN_SYSTEM.md`:\n- Use design tokens (no hardcoded colors/sizes).\n- Implement component states (hover/focus/disabled/loading/error).\n- Meet accessibility and performance requirements.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If ","type":"text"},{"text":"design-system-generator","type":"text","marks":[{"type":"code_inline"}]},{"text":" is NOT available:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Suggest installing","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"design-system-generator","type":"text","marks":[{"type":"code_inline"}]},{"text":" from:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://github.com/thienanblog/awesome-ai-agent-skills (project-development-skills plugin)","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Produce only:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" patch referencing ","type":"text"},{"text":"DESIGN_SYSTEM.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optional ","type":"text"},{"text":"minimal scaffold","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"DESIGN_SYSTEM.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (no deep recommendations)","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Minimal Scaffold for DESIGN_SYSTEM.md (only if design-system-generator unavailable)","type":"text"}]},{"type":"paragraph","content":[{"text":"If the user still wants a file now, generate ONLY this scaffold:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"# DESIGN_SYSTEM.md (Scaffold)\n\n## Scope\nDefines UI consistency rules for this project.\n\n## Tokens (TBD)\n- Colors: CSS variables\n- Typography: scale + line-height\n- Spacing: spacing scale\n- Radius/Shadows: scales\n\n## Components\nDefine component patterns and required states:\n- hover, focus, disabled, loading, error\n\n## Production assets\nUse hashed filenames + a manifest mapping to avoid cache issues.\nMinify CSS/JS and optimize images/fonts.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not pick Tailwind/MUI/shadcn/etc. in the scaffold unless the project already uses it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Never","type":"text","marks":[{"type":"strong"}]},{"text":" implement the full Design System logic inside ","type":"text"},{"text":"agents-md-generator","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Tech Stack Detection Reference","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/tech-stack-detection.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for complete detection patterns.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Section Templates Reference","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/section-templates.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for complete section templates per stack.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Update/Merge Strategy Reference","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/merge-strategy.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for detailed merge logic.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Progress Tracking (Maintainers)","type":"text"}]},{"type":"paragraph","content":[{"text":"When discussing or implementing new ideas/features for this skill, use ","type":"text"},{"text":"PROGRESS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the single continuity file.","type":"text"}]},{"type":"paragraph","content":[{"text":"Required ","type":"text"},{"text":"PROGRESS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" sections:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Original Prompt","type":"text","marks":[{"type":"code_inline"}]},{"text":" (verbatim user request that initiated the task)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Current Status","type":"text","marks":[{"type":"code_inline"}]},{"text":" (what is done, in progress, blocked)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Next Steps","type":"text","marks":[{"type":"code_inline"}]},{"text":" (clear continuation checklist)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Maintainer workflow:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"PROGRESS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" before starting any task.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Compare ","type":"text"},{"text":"Original Prompt","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"Current Status","type":"text","marks":[{"type":"code_inline"}]},{"text":" against the new request.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Continue unfinished work first when it matches the same objective.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update ","type":"text"},{"text":"Current Status","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"Next Steps","type":"text","marks":[{"type":"code_inline"}]},{"text":" before ending the task.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Archiving rule: keep ","type":"text"},{"text":"PROGRESS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" readable (about 200-300 lines max). Move old completed entries to ","type":"text"},{"text":"docs/archives/PROGRESS-YYYY-MM.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" when needed.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Output File Naming","type":"text"}]},{"type":"paragraph","content":[{"text":"Primary file:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"This is the main instruction file that AI agents read","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All edits should be made to this file","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep it concise; Codex has a combined project-doc size cap (","type":"text"},{"text":"project_doc_max_bytes","type":"text","marks":[{"type":"code_inline"}]},{"text":", 32 KiB by default)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use nested ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files for subprojects when closer-directory guidance should override broader guidance","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Codex override file:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"AGENTS.override.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Higher priority than ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for Codex in the same directory","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use only for Codex-specific, temporary, or nested-directory override rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not create by default because Codex includes at most one instruction file per directory","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Secondary file:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Normal text file for Claude Code compatibility","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"First line: ","type":"text"},{"text":"@AGENTS.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"May contain separate Claude-specific guidance only if the user explicitly wants parallel files","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Claude Code expands ","type":"text"},{"text":"@AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" when loading ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Why this approach:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Single source of truth prevents drift","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Works across all AI coding tools","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Avoids symbolic links that can cause duplicate context reads","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lets Claude Code share ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" through a lightweight file reference","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"This skill is part of the awesome-ai-agent-skills community library.","type":"text","marks":[{"type":"em"}]}]}]},"metadata":{"date":"2026-06-05","name":"agents-md-generator","author":"@skillopedia","source":{"stars":60,"repo_name":"awesome-ai-agent-skills","origin_url":"https://github.com/thienanblog/awesome-ai-agent-skills/blob/HEAD/skills/agents-md-generator/SKILL.md","repo_owner":"thienanblog","body_sha256":"bdb4ad24c95dfae70898ae3fa662883bde5bd18e45cfdfc03d5e7f320f6d5330","cluster_key":"334d2ecd4b127bb319e7527395d63845095103ada1e4ff28a1ddba1b3df3f694","clean_bundle":{"format":"clean-skill-bundle-v1","source":"thienanblog/awesome-ai-agent-skills/skills/agents-md-generator/SKILL.md","attachments":[{"id":"fd3413c3-428c-58a4-a0c4-429954caa16c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/fd3413c3-428c-58a4-a0c4-429954caa16c/attachment.md","path":"PROGRESS.md","size":1330,"sha256":"d6e886711d4cb6e8875ed3daddbb3e765454c2ba422a51828a55784cc03a7e77","contentType":"text/markdown; charset=utf-8"},{"id":"94381ae5-85f6-59b4-8023-4e17a9d3e151","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/94381ae5-85f6-59b4-8023-4e17a9d3e151/attachment.md","path":"ROADMAP.md","size":2599,"sha256":"406cc7b8c213a9541f271ae13d1349518f37970c4b11434ac306b85663b8f348","contentType":"text/markdown; charset=utf-8"},{"id":"f50dcbd7-23b0-5401-b3e6-280cf6bb6739","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f50dcbd7-23b0-5401-b3e6-280cf6bb6739/attachment.md","path":"assets/templates/generic.md","size":3249,"sha256":"0d1368bb63cf27980917caab942bea8b10c8a2c644c2ead70410172549ce6e68","contentType":"text/markdown; charset=utf-8"},{"id":"6d454e49-82ea-53e5-ab11-263899f035c8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6d454e49-82ea-53e5-ab11-263899f035c8/attachment.md","path":"assets/templates/laravel-backend.md","size":4353,"sha256":"3db674419cf1b709b359e8f7086eebc1b33957764cedd651aba56015da020cb7","contentType":"text/markdown; charset=utf-8"},{"id":"9cfd2229-640f-571e-9a6f-ab11101ac0e7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9cfd2229-640f-571e-9a6f-ab11101ac0e7/attachment.md","path":"assets/templates/laravel-fullstack.md","size":4791,"sha256":"3931fd7fb8c608a09bfb67f9b93f8474fb92ef67b4f6de7ed62036e968cf8bae","contentType":"text/markdown; charset=utf-8"},{"id":"bbdbd1c7-0944-51f1-a182-285845560c5a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bbdbd1c7-0944-51f1-a182-285845560c5a/attachment.md","path":"assets/templates/node-backend.md","size":6648,"sha256":"c02fe7eb76333ccd42e3e674d27c2b46d42e853fbf4ac78430d56b776c1c581c","contentType":"text/markdown; charset=utf-8"},{"id":"0f788ee5-b7da-5f19-8bd8-39a69e4a62da","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0f788ee5-b7da-5f19-8bd8-39a69e4a62da/attachment.md","path":"assets/templates/python-backend.md","size":8552,"sha256":"8cc5269e67c45545fee0a2a431306641b0e28512fade99abdfa380730b8edf26","contentType":"text/markdown; charset=utf-8"},{"id":"b7ef9150-c7fc-5180-b4ac-da5f1963db6f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b7ef9150-c7fc-5180-b4ac-da5f1963db6f/attachment.md","path":"assets/templates/react-frontend.md","size":5603,"sha256":"7788d61856881773ce684982c88d13a60373acac72ff36277bffce4d3c7c88d6","contentType":"text/markdown; charset=utf-8"},{"id":"0b4019f5-03e9-5a66-90f1-1ffc0828a6ae","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0b4019f5-03e9-5a66-90f1-1ffc0828a6ae/attachment.md","path":"assets/templates/vue-frontend.md","size":4449,"sha256":"fdca61520c0d11cc697d9e29ccc6a03806d1eeddb65d47035c5a8f015e4a6199","contentType":"text/markdown; charset=utf-8"},{"id":"b656c26e-ad70-55fc-b719-94bdc83464aa","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b656c26e-ad70-55fc-b719-94bdc83464aa/attachment","path":"docs/archives/.gitkeep","size":1,"sha256":"01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b","contentType":"text/plain; charset=utf-8"},{"id":"3020e7a0-65e1-5092-89e9-8b619279911c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3020e7a0-65e1-5092-89e9-8b619279911c/attachment.md","path":"references/merge-strategy.md","size":8788,"sha256":"ccabf06800e56151eb1be43e11d8f15905b50f775c23616bb04028cb6e9a8a42","contentType":"text/markdown; charset=utf-8"},{"id":"bfc9e6b7-69d6-517a-b069-307db382b0c0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bfc9e6b7-69d6-517a-b069-307db382b0c0/attachment.md","path":"references/section-templates.md","size":14694,"sha256":"4a43bec98f071563800149b7cacbbfbcc644e85d811c3c0f7992e9ddb89ba1a1","contentType":"text/markdown; charset=utf-8"},{"id":"a86aea74-8ff2-5623-8fbe-68d79cba0319","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a86aea74-8ff2-5623-8fbe-68d79cba0319/attachment.md","path":"references/tech-stack-detection.md","size":16557,"sha256":"f2c92855234dc6f8061e792c846ba219ecaea1726decec80dc6b52c7b7d84cfe","contentType":"text/markdown; charset=utf-8"},{"id":"44aee2a2-2c6f-5880-bd56-49d82eade46d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/44aee2a2-2c6f-5880-bd56-49d82eade46d/attachment","path":"scripts/archive-roadmap-progress","size":1646,"sha256":"2990c5e7b519f67edbf0defebea4d529459dece008b8ede7451c12f14ce9717c","contentType":"text/plain; charset=utf-8"},{"id":"49872462-cefb-542f-b55d-d3b739f4548d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/49872462-cefb-542f-b55d-d3b739f4548d/attachment.cmd","path":"scripts/archive-roadmap-progress.cmd","size":1121,"sha256":"d035af19734db14db6d162c43498beb4d5d129e2e691996ab94d2f807e4ce2f4","contentType":"text/plain; charset=utf-8"},{"id":"e84ff0a3-c5ea-5276-906d-bcc9e11e9ec4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e84ff0a3-c5ea-5276-906d-bcc9e11e9ec4/attachment.ps1","path":"scripts/archive-roadmap-progress.ps1","size":4508,"sha256":"55f503d9d90d5d77572733eb13e8aea76bd791a7eda2a22a85f6fb3c2ddc3e86","contentType":"text/plain; charset=utf-8"},{"id":"c8e8192f-d5ae-54c5-a823-6e71d389637b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c8e8192f-d5ae-54c5-a823-6e71d389637b/attachment.sh","path":"scripts/archive-roadmap-progress.sh","size":5940,"sha256":"ef5ab8c2b4d1e14bae5cabbca0097a541be34ce012b36dac14a333510f747487","contentType":"application/x-sh; charset=utf-8"},{"id":"bbb23525-694c-508b-bbb4-3c02a8b6a766","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bbb23525-694c-508b-bbb4-3c02a8b6a766/attachment","path":"scripts/detect-agent-context","size":1521,"sha256":"cda7dcc1999f31827d736d7a79d269460c18ccaf42edf54f71665acab5cacd4c","contentType":"text/plain; charset=utf-8"},{"id":"b8be4adb-1b12-5089-8d6e-12cec5d40bae","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b8be4adb-1b12-5089-8d6e-12cec5d40bae/attachment.cmd","path":"scripts/detect-agent-context.cmd","size":858,"sha256":"7375f07519a0e13402349e667fa55dfabfa427c2825381096dcca72c8620d385","contentType":"text/plain; charset=utf-8"},{"id":"eb1a3448-f4d1-5568-8145-536634b7039c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/eb1a3448-f4d1-5568-8145-536634b7039c/attachment.ps1","path":"scripts/detect-agent-context.ps1","size":5198,"sha256":"b16ed47c78ec0a73d80ca3ee90fd9e04a7645c659915a67ab85e94474e7684ba","contentType":"text/plain; charset=utf-8"},{"id":"81d6cfcf-4fc9-5088-8dd0-05ed7e199a08","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/81d6cfcf-4fc9-5088-8dd0-05ed7e199a08/attachment.sh","path":"scripts/detect-agent-context.sh","size":5669,"sha256":"8915a502cc9da3275cdf6426aa1998e7d7952eb3a207c00ebea1d5707607e66a","contentType":"application/x-sh; charset=utf-8"},{"id":"bccf18fb-afa6-5875-94f2-4c4690a6782a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bccf18fb-afa6-5875-94f2-4c4690a6782a/attachment","path":"scripts/scan-skill-duplicates","size":1523,"sha256":"31c8dad8b36a78eb159eb74dd2f2481ecb99e1e1e8256d71966743f8e187f77b","contentType":"text/plain; charset=utf-8"},{"id":"14ef4414-20ca-5be5-9dd2-fbef91ad1754","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/14ef4414-20ca-5be5-9dd2-fbef91ad1754/attachment.cmd","path":"scripts/scan-skill-duplicates.cmd","size":747,"sha256":"63f0b6adb57d20f09c69c678cd914b46251e91f14fe6c267233a25bd1864e404","contentType":"text/plain; charset=utf-8"},{"id":"8b4cbaa4-adc8-5083-ba02-090512bc77aa","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8b4cbaa4-adc8-5083-ba02-090512bc77aa/attachment.ps1","path":"scripts/scan-skill-duplicates.ps1","size":2491,"sha256":"46a547bc52575afdc76d2e9473099ee50f83414da5c80feb14fb079ee44d8d56","contentType":"text/plain; charset=utf-8"},{"id":"fbda7f0d-bb94-5f89-83af-29606ba6dc58","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/fbda7f0d-bb94-5f89-83af-29606ba6dc58/attachment.sh","path":"scripts/scan-skill-duplicates.sh","size":3100,"sha256":"88ffa1fd92b233e30a74b1b5409b33afae9f07880e9c4329c99d7a20d848c9f2","contentType":"application/x-sh; charset=utf-8"}],"bundle_sha256":"4665606a9cd47c1763e6f1c463b29bace4d32a4c8b4800dfc57318a214b97382","attachment_count":25,"text_attachments":15,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":10,"excluded_attachments":[]},"cluster_size":2,"skill_md_path":"skills/agents-md-generator/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"software-engineering","category_label":"Engineering"},"exact_dupes_collapsed_into_this":1},"context":"fork","version":"v1","category":"software-engineering","import_tag":"clean-skills-v1","description":"Generate or update AGENTS.md/CLAUDE.md files for AI coding agents through auto-scanning project files combined with interactive Q&A. Supports multiple tech stacks, development environments, and preserves customizations when updating."}},"renderedAt":1782980529923}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.