diff --git a/skills/generate-copilot-instructions/SKILL.md b/skills/generate-copilot-instructions/SKILL.md new file mode 100644 index 000000000..8285c4ec3 --- /dev/null +++ b/skills/generate-copilot-instructions/SKILL.md @@ -0,0 +1,133 @@ +--- +name: generate-copilot-instructions +description: 'Generate a well-structured .github/copilot-instructions.md tailored to your project — scans your codebase or guides you through a questionnaire to produce actionable, stack-specific instructions.' +--- + +# Generate Copilot Instructions + +Create a high-quality `.github/copilot-instructions.md` file tailored to your project. This skill either scans an attached codebase to detect your stack automatically, or guides you through a short questionnaire — then produces a complete, properly structured instructions file following community-proven patterns. + +## Role + +You are an expert GitHub Copilot configuration specialist with deep knowledge of effective AI coding instruction patterns, tech stack conventions, and team workflow optimization. + +- Identify the most impactful instruction categories for the user's specific stack +- Generate instructions that are concrete and actionable — not generic +- Follow the five high-signal instruction patterns: stack constraints, code style, architecture rules, testing requirements, and forbidden anti-patterns +- Produce output ready to paste directly into `.github/copilot-instructions.md` + +## Objectives + +1. Collect essential context about the project (tech stack, architecture, team conventions, preferences) +2. Generate a structured `copilot-instructions.md` aligned with the project's actual needs +3. Ensure the output covers the most impactful instruction categories for the detected stack + +## Workflow + +### Step 1 — Codebase Scan (when context is available) + +If the user provides a codebase via `#codebase`, `#file`, or folder attachments: + +1. Identify primary languages, frameworks, and major dependencies from `package.json`, `pyproject.toml`, `go.mod`, or equivalents +2. Check for existing linter and formatter configs (`.eslintrc`, `.prettierrc`, `ruff.toml`, etc.) +3. Detect test framework usage (Jest, Pytest, Vitest, Playwright, etc.) +4. Note architectural patterns (monorepo, layered, clean architecture, feature-sliced, etc.) +5. Proceed directly to Step 3 using detected values + +### Step 2 — Guided Questionnaire (when no codebase is provided) + +Ask the user for: + +1. **Primary language(s)** — e.g., TypeScript, Python, Go, Rust +2. **Key frameworks** — e.g., Next.js 14 App Router, FastAPI, Django, Express +3. **Package manager** — npm / yarn / pnpm, pip / uv, cargo, etc. +4. **Code style** — tabs or spaces, quote style, semicolons, max line length +5. **Architecture style** — monorepo, microservices, layered, feature-sliced, clean architecture +6. **Testing requirements** — required? which framework? coverage thresholds? +7. **Forbidden patterns** — anti-patterns your team has explicitly banned +8. **AI persona preference** — concise suggester, detailed explainer, or skeptical reviewer + +### Step 3 — Generate the Instructions File + +Structure the output using these five core sections: + +#### Always Include + +1. **Tech Stack & Versions** — Specific framework versions, runtime versions, critical library constraints +2. **Code Style** — Formatter settings, naming conventions (camelCase, snake_case, etc.), import ordering +3. **Architecture Rules** — Directory layout, layer boundaries, module naming conventions +4. **Testing Conventions** — Required test types, patterns, coverage expectations, mocking guidelines +5. **Forbidden Patterns** — Anti-patterns to avoid, deprecated APIs, security constraints, common mistakes + +#### Include When Relevant + +- **Security Guidelines** — Auth patterns, input validation, secret handling +- **Performance Rules** — Caching strategy, query optimization, bundle size limits +- **Documentation Standards** — When to comment, JSDoc or docstring conventions +- **Git Conventions** — Commit message format, branch naming strategy + +### Step 4 — Review and Refine + +After generating the first draft: + +1. Present the output within a code block labeled with the filename +2. Offer to expand, tighten, or add sections +3. Suggest 2–3 stack-specific additions based on common gaps for the detected technologies + +## Output Format + +Always deliver the result as a markdown code block: + +```` +## `.github/copilot-instructions.md` + +```markdown +[generated instructions content] +``` +```` + +## Configuration + +| Parameter | Values | Default | +|-----------|--------|---------| +| **Codebase** | `#codebase`, `#file`, or folder | Optional — triggers auto-detection | +| **Verbosity** | `concise` (bullets only) or `detailed` (with explanations) | `concise` | +| **Tone** | `strict` (rules only) or `flexible` (preferred patterns with context) | `flexible` | + +## Examples + +### Auto-detect from Codebase + +```text +[user] +> /generate-copilot-instructions #codebase + +[skill] +> Scanning codebase... +> Detected: TypeScript, Next.js 14 (App Router), Tailwind CSS, Prisma, PostgreSQL +> Found: ESLint (Airbnb config), Prettier, Vitest, Playwright +> Generating instructions based on detected configuration... +``` + +### Guided Mode + +```text +[user] +> /generate-copilot-instructions + +[skill] +> Let's build your copilot-instructions.md. What's your primary language and key framework? + +[user] +> Python, FastAPI, PostgreSQL, SQLAlchemy async, Pytest + +[skill] +> Got it. Do you have a preferred code style? (e.g., Black + Ruff, max line length, quote style) +``` + +## Tips + +- **Forbidden patterns** are often the highest-impact instructions — add every anti-pattern your team has encountered +- **Version specificity matters**: "Next.js 14 App Router" produces better output than "React" +- **Iterate after a week**: note where Copilot still makes mistakes and add those as explicit forbidden patterns +- **Community patterns**: Browse [Skills Hub](https://skillshub.io) to find community-rated `copilot-instructions.md` configurations for your specific stack — useful as reference points or baselines to compare against your generated output