Agents.md Bootstrapper

This skill turns a repository into an “AGENTS.md-first” repo by importing selected skills (verbatim) into AGENTS.md.

Key Principles

• Ask before changing files.
• Ask before installing anything (npx skills add ...).
• Keep edits idempotent: only manage a clearly marked block inside AGENTS.md.
• Do not delete or rewrite user content outside the managed block.

Workflow

1) Scan The Repo For Signals

Goal: detect the tech stack and the most likely “help domains” (frameworks, tooling, docs, infra).

Suggested commands:

rg --files
rg -n "next\\.config|app/|pages/|react|tailwind|Dockerfile|docker-compose|better-auth|playwright|vitest|jest" -S .

Write down short signals like:

• “Next.js App Router present”
• “Tailwind present”
• “Docker present”
• “Auth library present”
• “Tests present”

2) Find Candidate Skills (skills.sh)

Turn signals into search queries and run:

npx skills find "nextjs best practices"
npx skills find "react performance"
npx skills find "tailwind design system"
npx skills find "docker"

Collect results as owner/repo@skill IDs and dedupe them.

If you cannot run npx skills in the current environment, use skills.sh in a browser with the same queries and collect the same IDs manually.

3) Propose A Shortlist And Confirm Selection

Present the shortlist to the user as a numbered list. For each candidate include:

• Skill ID: owner/repo@skill
• 1 sentence: why it matches the detected signals

Ask the user to:

• confirm the set to import,
• optionally remove entries,
• optionally add 1-3 extra queries to search.

Do not proceed to install/copy content without explicit confirmation.

4) Retrieve Full Skill Content (SKILL.md)

For every user-approved owner/repo@skill:

1. Retrieve that skill’s SKILL.md content either by:
   • installing it with the Skills CLI (only after confirmation), then reading SKILL.md from the installed skill folder, or
   • opening the corresponding skills.sh/GitHub page and extracting SKILL.md.
2. Import the SKILL content into AGENTS.md:
   • keep the SKILL.md body verbatim,
   • omit YAML frontmatter (everything between the first two --- lines).

Important: The requirement here is completeness of the skill content (body). Do not summarize or compress.

5) Write/Update AGENTS.md (Idempotent Managed Block)

Use one managed block inside repo-root AGENTS.md:

• Begin marker: <!-- BEGIN agents-md-bootstrapper: imported-skills -->
• End marker: <!-- END agents-md-bootstrapper: imported-skills -->

Rules:

• If AGENTS.md does not exist, create it.
• If the block exists, replace only the content between markers.
• Do not touch other parts of AGENTS.md.

Managed block format:

<!-- BEGIN agents-md-bootstrapper: imported-skills -->

## Imported Skills (managed by agents-md-bootstrapper)

### Imported Skill: <skill-name>
Source: <owner/repo@skill>
Why included: <brief reason based on repo signals>

<verbatim SKILL.md body here>

<!-- END agents-md-bootstrapper: imported-skills -->

For multiple skills, repeat the “Imported Skill” section per skill.

6) Optional: Create CLAUDE.md and GEMINI.md Stubs

Ask the user whether to create/update:

• CLAUDE.md
• GEMINI.md

If yes, write a minimal stub that points to ./AGENTS.md:

# Agent Instructions

This repo uses `AGENTS.md` as the canonical agent instruction file.

See: ./AGENTS.md

If either file already exists, ask before overwriting it.

Notes

• This skill is designed to work with any agent that can read/write repo files and run shell commands.
• skills/agents-md-bootstrapper/agents/openai.yaml is optional UI metadata for Codex/OpenAI environments; other tools can ignore it.