8.4 KiB
AI Overview
You are here: AI Docs Home > AI Overview
Contents
- Start Here
- Quick Setup Verification
- Terminology
- Where AI Assets Live
- Agents vs Skills
- How To Evaluate AI Output
- Chat Types And Modes
- Guardrails And Next Steps
Start Here
AI tools help with drafting, refactoring, explaining code, and accelerating routine tasks. They are not a replacement for engineering judgment, security review, or domain knowledge.
What To Expect In The First 30 Minutes
- Confirm you have access to GitHub Copilot Enterprise.
- Install the editor plugin for your platform.
- Run a simple prompt to verify suggestions appear.
- Read the usage and token guidance to avoid accidental overuse.
Quick Setup Verification
Use this checklist after install so you know things are working:
- Open a code file and type a short comment prompt.
- Confirm an inline suggestion appears within a few seconds.
- Open Copilot Chat and ask a short question.
- If nothing appears, restart the editor and try again.
- If still blocked, follow Troubleshooting and FAQ.
What AI Is and Is Not
- AI is a productivity assistant that can suggest code, summarize context, and propose solutions.
- AI is not a source of truth. Always validate outputs with tests, code review, and domain checks.
Example (Good vs Risky)
Example prompts:
Good: Summarize this file and list the top 3 risks.
Risky: Rewrite this subsystem without review.
GitHub Copilot Enterprise
What It Is
Copilot is an AI coding assistant that integrates with editors and chats to help you write and understand code.
Access Requirements
- You must be provisioned for Copilot Enterprise by the org.
- You must sign in with your GitHub account that has access.
Setup Steps (High-Level)
- Confirm access with your team or admin.
- Sign in to GitHub in your editor or plugin.
- Verify Copilot is enabled in editor settings.
- Run a quick prompt to validate it works.
What You Should See
- A Copilot icon or status indicator in your editor.
- Inline code suggestions as you type.
- A chat panel that can answer questions.
Quick Access Checklist
- GitHub account is linked to the org.
- SSO or required auth flow is completed.
- Copilot is enabled in the editor or plugin settings.
Terminology
- Copilot: The AI assistant integrated into your editor.
- Chat: The conversational interface in your editor.
- Agents: Structured workflows that break work into steps.
- Skills: Reusable knowledge or workflows the assistant can apply.
- Tokens: The usage units that track AI consumption.
Where AI Assets Live (File Layout)
Use this mental model so you know what is repo-scoped vs global:
Repo (this guide)
docs/ai/ # Handbook content
assets/agents/ # Repo-shipped agent prompts
assets/instructions/ # Repo-shipped instructions
User machine (global)
~/.agents/skills/ # Approved skills pulled by sync
~/.agents/agents/ # Optional global agents
Instructions (Repo Rules)
Instructions are repo-scoped rule files that auto-apply based on file patterns. They set coding or documentation standards the assistant must follow when editing matching files.
Where they live:
- The repo-level instructions directory (for example, assets/instructions/)
- Editor or org-level instruction files when configured by your team
Instructions are always-on defaults. Agents and skills are optional and only used when you explicitly invoke them.
Agents.md vs Instructions
Agents.md is a human-readable contributor guide for how to work in this repo (request format, plan-first habits, and sync expectations). It does not apply automatically.
Instructions files are machine-readable rules that auto-apply when you edit matching files. They are enforced by the assistant without you having to reference them.
Agents vs Skills (Where They Live)
Agents are full personas or modes (for example, Task Researcher) that control how the assistant behaves end-to-end. Skills are focused, reusable workflows (for example, webapp-testing) that the assistant can load for a specific task.
Where they live:
- Agents can be stored in a repo (project-specific) or in a user-level folder for global reuse.
- Skills are typically installed globally via the approved skills directory and synced with a manifest.
If you need the official agent assets repo, ask your team lead or check your internal setup docs.
How To Evaluate AI Output (Quick Rubric)
Before you accept changes, check:
- Correctness: Does it compile or pass tests?
- Scope: Did it change only what you asked for?
- Safety: No secrets, no policy violations, no risky changes.
- Tests: Are new tests required or existing tests updated?
- Review: Would you approve this in code review?
Example Review Prompt
Example prompt:
Review this change for correctness, scope creep, and missing tests. Keep the response under 8 bullets.
Key Repo Files (Why They Exist)
These files explain how the AI docs are organized and how contributors should work. Each one has a different job.
Agents.md
What it is: The workflow rules for using AI in this repo.
Why you create it: It keeps requests consistent so changes are scoped, reviewable, and repeatable.
What to include:
- Request structure (goal, inputs, output, verification).
- Plan-first guidance for multi-step changes.
- Sync rule: keep PRD.md and README.md aligned when workflows or scope change.
Project example: See Agents.md for the request template and contribution workflow used in this repo.
PRD.md
What it is: The product requirements for the documentation set.
Why you create it: It anchors scope and success metrics so the docs do not drift.
What to include:
- Problem statement, goals, and non-goals.
- Target audience and user stories.
- Content requirements (step-by-step guidance and examples).
- Definition of done and sync expectations.
Project example: See PRD.md for the requirements and definition of done used here.
README.md
What it is: The entry point for contributors and readers who need quick orientation.
Why you create it: It tells people what the repo is, where to start, and how to contribute.
What to include:
- Repo purpose and audience.
- Where to start (index, overview, setup guides).
- Contribution habits and publishing steps.
Project example: See README.md for the start-here links and local workflow.
Chat Types In Plain English
Copilot chat has four modes. Pick the smallest one that fits the task.
Ask: Quick questions, summaries, or explanations. Edit: Small, specific changes with constraints. Plan: A step-by-step plan before edits. Agent: Multi-step work across files with checks.
Example prompts:
Ask: Summarize this file in 5 bullets and list 2 risks.
Edit: Update this function to return nil when the input is empty. Keep behavior the same otherwise.
Plan: Give me a 6-step plan to add caching to this service. Wait for approval before edits.
Agent: Refactor these two files, update unit tests, then summarize the changes and test results.
Example: Chat vs Agents
Example prompts:
Chat: What does this function do?
Agent: Plan and refactor this module, then list tests to add.
Choosing The Right Chat Mode (Decision Tree)
- Do you only need an explanation or summary? Use Ask.
- Do you want a small edit in one file? Use Edit.
- Do you want steps before any edits? Use Plan.
- Do you want multi-step work across files or tools? Use Agent.
First Prompt (Safe)
Try a small, safe prompt to confirm everything is working:
Summarize what this file does in 3 bullet points.
Guardrails And Good Habits
- Keep prompts scoped to a single task.
- Ask for a plan before large changes.
- Verify outputs with tests and review.
- Avoid sharing secrets or sensitive data.
Example: Safe Prompt
Example prompt:
Refactor only the validation logic in this file. Keep behavior the same and list tests to update.
Next Steps
- If you have not set up an editor yet, go to iOS Setup or Android Setup.
- For day-to-day usage patterns, read Cross-Platform AI Usage.
- For safety and cost guidance, read Governance, Privacy, and Policy and Usage and Token Budgeting.
Getting Help
- Ask your team lead or the AI docs owner.
- Use the escalation guidance in Troubleshooting and FAQ.