diff --git a/.github/instructions/python-standards.instructions.md b/.github/instructions/python-standards.instructions.md new file mode 100644 index 00000000..b249c570 --- /dev/null +++ b/.github/instructions/python-standards.instructions.md @@ -0,0 +1,25 @@ +--- +applyTo: "**/*.py" +--- + +# Python Standards + +These rules apply automatically whenever Copilot works on a Python file in +this project. They never load for other file types, so a conversation about a +Dockerfile or some JSON stays clutter-free. + +## Style + +- Follow PEP 8 style conventions. +- Add type hints to every function signature. +- Prefer f-strings over `%` formatting or `str.format()`. + +## Error Handling + +- Catch specific exceptions; never use a bare `except:`. +- Validate inputs at function boundaries and fail with a clear message. + +## Testing + +- Put pytest tests in `samples/book-app-project/tests/` using `test_*.py` naming. +- Cover the happy path and edge cases (empty input, missing data). diff --git a/.github/uvs.csv b/.github/uvs.csv index 8f22da24..10e144b1 100644 --- a/.github/uvs.csv +++ b/.github/uvs.csv @@ -109,3 +109,38 @@ "06/19",568 "06/20",227 "06/21",244 +"06/22",650 +"06/23",591 +"06/24",583 +"06/25",565 +"06/26",517 +"06/27",241 +"06/28",287 +"06/29",605 +"06/30",550 +"07/01",492 +"07/02",419 +"07/03",497 +"07/04",198 +"07/05",226 +"07/06",507 +"07/07",441 +"07/08",490 +"07/09",474 +"07/10",463 +"07/11",377 +"07/12",336 +"07/13",478 +"07/14",497 +"07/15",426 +"07/16",407 +"07/17",474 +"07/18",213 +"07/19",238 +"07/20",481 +"07/21",434 +"07/22",418 +"07/23",461 +"07/24",431 +"07/25",204 +"07/26",211 diff --git a/.github/views.csv b/.github/views.csv index 2938b6b7..3d1e369d 100644 --- a/.github/views.csv +++ b/.github/views.csv @@ -108,3 +108,38 @@ "06/19",1319 "06/20",589 "06/21",552 +"06/22",1348 +"06/23",1152 +"06/24",1154 +"06/25",1230 +"06/26",1066 +"06/27",593 +"06/28",590 +"06/29",1184 +"06/30",1116 +"07/01",1035 +"07/02",1032 +"07/03",1199 +"07/04",495 +"07/05",794 +"07/06",2370 +"07/07",2880 +"07/08",4565 +"07/09",4512 +"07/10",904 +"07/11",850 +"07/12",788 +"07/13",981 +"07/14",980 +"07/15",924 +"07/16",822 +"07/17",1162 +"07/18",485 +"07/19",596 +"07/20",1041 +"07/21",881 +"07/22",878 +"07/23",958 +"07/24",1014 +"07/25",547 +"07/26",507 diff --git a/.github/workflows/translation-polisher.md b/.github/workflows/translation-polisher.md index 4d9202ab..7eff0d74 100644 --- a/.github/workflows/translation-polisher.md +++ b/.github/workflows/translation-polisher.md @@ -107,7 +107,11 @@ Do not edit: ## Required process -1. Identify the target pull request number and head branch. +> **Shell tooling constraint:** Only the `gh`, `git`, and `node` commands are available in this environment. Do **not** call `python`, `python3`, `sed`, `awk`, or `grep` pipelines — they are not permitted and will fail with a permission error. Filter and process command output yourself instead of piping through unsupported tools. + +1. Identify the target pull request number and head branch, then list the files the pull request changed. Use only the available shell tools: + - List changed files with `git diff --name-only origin/main...HEAD` (the branch is checked out with full history) or `gh pr diff --name-only`. + - From that output, select only files matching `translations/**/*.md`, and ignore `translations/*/.github/**` and `translations/*/samples/**`. Do this selection yourself from the file list rather than piping through `grep`/`sed`. 2. Compare each changed translated Markdown file with its corresponding English source file. - Example: compare `translations/es/README.md` with `README.md`. - Example: compare `translations/es/03-development-workflows/README.md` with `03-development-workflows/README.md`. diff --git a/01-setup-and-first-steps/README.md b/01-setup-and-first-steps/README.md index 39afb9ac..13afdafe 100644 --- a/01-setup-and-first-steps/README.md +++ b/01-setup-and-first-steps/README.md @@ -325,7 +325,7 @@ Step 4: Test the flow Proceed with implementation? [Y/n] ``` -**Key insight**: Plan mode lets you review and modify the approach before any code is written. Once a plan is complete, you can even tell Copilot CLI to save it to a file for later reference. For example, "Save this plan to `mark_as_read_plan.md`" would create a markdown file with the plan details. +**Key insight**: Plan mode lets you review and modify the approach before any code is written. While in plan mode, Copilot CLI is **read-only** and will not edit any files or run commands that change your workspace until you approve and move to implementation. This keeps you safely in the "thinking" stage until you're ready. Once a plan is complete, you can even tell Copilot CLI to save it to a file for later reference. For example, "Save this plan to `mark_as_read_plan.md`" would create a markdown file with the plan details. > 💡 **Want something more complex?** Try: `/plan Add search and filter capabilities to the book app`. Plan mode scales from simple features to full applications. @@ -383,11 +383,14 @@ These commands are great to learn initially as you're getting started with Copil | `/help` | Show all available commands | When you forget a command | | `/model` | Show or switch AI model | When you want to change the AI model | | `/plan` | Plan your work out before coding | For more complex features | +| `/refine` | Rewrite a rough, stream-of-consciousness prompt into a clear, focused one | When your prompt feels messy and you want better results | | `/research` | Deep research using GitHub and web sources | When you need to investigate a topic before coding | | `/exit` | End the session | When you're done | > 💡 **`/ask` vs regular chat**: Normally every message you send becomes part of the ongoing conversation and affects future responses. `/ask` is an "off the record" shortcut — perfect for quick one-off questions like `/ask What does YAML mean?` without polluting your session context. +> 💡 **`/refine` for better prompts**: Not sure if your prompt is clear enough? Type it out as it comes to mind, then run `/refine` to let Copilot rewrite it into a precise, well-structured prompt before sending. This is especially useful when you're new to AI tools and still learning how to write effective prompts. + > 💡 **Tab-completion**: When typing a slash command, press **Tab** to auto-complete the command name or cycle through available subcommands and arguments. This is especially handy when you can't remember the exact name of a command. That's it for getting started! As you become comfortable, you can explore additional commands. @@ -666,7 +669,7 @@ The examples used `/plan` for a search feature and `-p` for batch reviews. Now t |---------|--------------|-----| | Typing `exit` instead of `/exit` | Copilot CLI treats "exit" as a prompt, not a command | Slash commands always start with `/` | | Using `-p` for multi-turn conversations | Each `-p` call is isolated with no memory of previous calls | Use interactive mode (`copilot`) for conversations that build on context | -| Forgetting quotes around prompts with `$` or `!` | Shell interprets special characters before Copilot CLI sees them | Wrap prompts in quotes: `copilot -p "What does $HOME mean?"` | +| Forgetting quotes around prompts with `$` or `!` | Shell interprets special characters before Copilot CLI sees them | Wrap prompts in single quotes: `copilot -p 'What does $HOME mean?'` | | Pressing Esc once to cancel a running task | A single Esc no longer cancels in-flight work (to prevent accidents) | Press **Esc twice** to cancel while Copilot CLI is processing | ### Troubleshooting diff --git a/03-development-workflows/README.md b/03-development-workflows/README.md index bacb7ffb..0116c50f 100644 --- a/03-development-workflows/README.md +++ b/03-development-workflows/README.md @@ -582,7 +582,7 @@ copilot
-Workflow 5: Git Integration - Commit messages, PR descriptions, /pr, /delegate, and /diff +Workflow 5: Git Integration - Commit messages, PR descriptions, /pr, /delegate, /diff, and /branch Git Integration workflow: stage changes, generate message, commit, create PR. @@ -691,7 +691,7 @@ This is great for well-defined tasks you want completed while you focus on other ### Using /diff to Review Session Changes -The `/diff` command shows all changes made during your current session. Use this slash command to see a visual diff of everything Copilot CLI has modified before you commit. +The `/diff` command shows all changes made during your current session. Use this slash command to see a visual diff of everything Copilot CLI has modified before you commit. It also works in folders that aren't git repositories. ```bash copilot @@ -703,6 +703,28 @@ copilot # Great for reviewing before committing ``` +### Branching Your Session with /branch or /fork + +Sometimes you want to explore two different approaches to a problem without losing your original conversation. The `/branch` command (also available as `/fork`) creates a copy of your current session so you can try a different direction and then compare results. + +```bash +copilot + +> Fix the find_by_author function to support partial matches + +# You want to try a different approach — branch first! +> /branch + +# Now you're in a new session copy. Try your alternative approach: +> Fix find_by_author using a different regex-based strategy + +# If you don't like the result, switch back to your original session using /session +``` + +> 💡 **`/branch` and `/fork` are the same**: Both commands do identical things. `/branch` was added as a more intuitive name. Use whichever makes more sense to you. + +> 💡 **When to branch**: Branching is great when you're unsure which approach is better and want to keep both options open. +
--- diff --git a/04-agents-custom-instructions/README.md b/04-agents-custom-instructions/README.md index 8494273a..7e84bf23 100644 --- a/04-agents-custom-instructions/README.md +++ b/04-agents-custom-instructions/README.md @@ -107,8 +107,27 @@ What about the Task Agent? It works behind the scenes to manage and track what i | ✅ **Success** | Brief summary (e.g., "All 247 tests passed", "Build succeeded") | | ❌ **Failure** | Full output with stack traces, compiler errors, and detailed logs | +> 💡 **Multi-turn subagents**: Subagents (background tasks launched by agents) support follow-up messages. While an agent is running in the background, you can open `/tasks` to view it and send follow-up instructions. You don't have to wait for it to finish before guiding it further. Think of it like being able to tap your assistant on the shoulder mid-task to give extra direction. -> 📚 **Official Documentation**: [GitHub Copilot CLI Agents](https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli#use-custom-agents) +### Choosing a Model for Plan Mode + +By default, `/plan` uses the same AI model you've selected for your session. You can pick a *different* model to use only while in plan mode — great for using a faster or less expensive model for planning, then switching back to a more powerful one for implementation: + +```bash +copilot + +# Open the model picker for plan mode only +> /model plan + +# Or specify a model ID directly (use 'off' to clear the plan-mode model) +> /model plan gpt-5.6-sol + +# Leave plan mode and the model reverts to your session model automatically +``` + +> 💡 **Why set a plan-mode model?** A high-quality plan created by a frontier model upfront can actually save tokens and time overall. A precise, well-scoped plan means fewer back-and-forth corrections during implementation. + +> 📚 **Official Documentation**: [GitHub Copilot CLI Agents](https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents) --- @@ -486,6 +505,22 @@ Here are some common patterns: > 💡 **Tip**: Wrap the glob pattern in quotes (e.g., `"**/*.py"`) to ensure it is interpreted correctly across all operating systems and shells. +#### Importing Other Files with `@` + +You can reference another file inside `AGENTS.md` or any instruction file using `@filepath` syntax. Copilot expands the reference and includes that file's content automatically, so you can keep your main file short while storing the details elsewhere: + +```markdown + +# Project Instructions + +@.github/instructions/python-standards.instructions.md +@.github/instructions/test-standards.instructions.md +``` + +This is handy when your instructions grow large. Split them into focused files and `@`-import them from a single `AGENTS.md`. The same syntax works inside `.github/copilot-instructions.md` and other instruction files too. + +> 💡 **Tip**: Use `@`-imports to share a common base file across multiple instruction files. For example, you could have a `@.github/instructions/shared-rules.md` that every other instruction file pulls in. + **Finding community instruction files**: Browse [github/awesome-copilot](https://github.com/github/awesome-copilot) for pre-made instruction files covering .NET, Angular, Azure, Python, Docker, and many more technologies. ### Disabling Custom Instructions diff --git a/05-skills/README.md b/05-skills/README.md index 829c4dcb..80e5bad0 100644 --- a/05-skills/README.md +++ b/05-skills/README.md @@ -369,6 +369,9 @@ Provide issues as a numbered list with severity: | `name` | **Yes** | Unique identifier (lowercase, hyphens for spaces) | | `description` | **Yes** | What the skill does and when Copilot should use it | | `license` | No | License that applies to this skill | +| `argument-hint` | No | Short hint shown to users describing what argument the skill expects (e.g., `"file path or code snippet"`) | + +> 💡 **What is `argument-hint`?** When users invoke a skill directly (e.g., `/security-audit`), the `argument-hint` text appears as a placeholder showing what to type next — like a mini help prompt. For example, setting `argument-hint: "file path to review"` tells the user to provide a file path after the skill name. > 📖 **Official docs**: [About Agent Skills](https://docs.github.com/copilot/concepts/agents/about-agent-skills) @@ -487,9 +490,29 @@ Discover installed skills, find community skills, and share your own. --- -## Managing Skills with the `/skills` Command +## Managing Skills with the `copilot skill` Command and `/skills` + +Copilot CLI gives you two ways to manage skills. You can do it directly from the terminal before starting Copilot or from inside a Copilot session. + +### Option 1: `copilot skill` (Terminal Command) + +The `copilot skill` subcommand lets you manage skills directly from your terminal, without opening an interactive Copilot session. This is handy for scripting, quick checks, or adding skills before you start working. + +```bash +# See all installed skills +copilot skill list + +# Add a skill from a local file, URL, or directory +copilot skill add .github/skills/my-skill/SKILL.md +copilot skill add https://example.com/skills/security-audit/SKILL.md + +# Remove a skill by name +copilot skill remove security-audit +``` -Use the `/skills` command to manage your installed skills: +### Option 2: `/skills` (Inside Copilot Session) + +Once you're in an interactive Copilot session, use `/skills` (or its shortcut `/skill`) to manage skills without leaving: | Command | What It Does | |---------|--------------| @@ -499,19 +522,31 @@ Use the `/skills` command to manage your installed skills: | `/skills remove ` | Disable or uninstall a skill | | `/skills reload` | Reload skills after editing SKILL.md files | +> 💡 **`/skill` shortcut**: You can type `/skill` instead of `/skills` — they're interchangeable. For example, `/skill list` works the same as `/skills list`. + > 💡 **Remember**: You don't need to "activate" skills for each prompt. Once installed, skills are **automatically triggered** when your prompt matches their description. These commands are for managing which skills are available, not for using them. ### Example: View Your Skills ```bash +# From the terminal (no interactive session needed): +copilot skill list + +Project skills: +- security-audit: Security-focused code review checking OWASP Top 10 +- generate-tests: Generate comprehensive unit tests with edge cases +- code-checklist: Team code quality checklist (disabled) +... + +# Or from inside a Copilot session: copilot > /skills list -Available skills: +Project skills: - security-audit: Security-focused code review checking OWASP Top 10 - generate-tests: Generate comprehensive unit tests with edge cases -- code-checklist: Team code quality checklist +- code-checklist: Team code quality checklist (disabled) ... > /skills info security-audit @@ -522,6 +557,8 @@ Location: .github/skills/security-audit/SKILL.md Description: Security-focused code review checking OWASP Top 10 vulnerabilities ``` +> 💡 **Disabled skills**: Skills marked as `(disabled)` are installed but not currently active. They won't be triggered by prompts until re-enabled. This can happen if a skill's `SKILL.md` file has a configuration issue, or if the skill was explicitly disabled. You can enable/disable skills by running `/skills`. + ---
@@ -873,9 +910,10 @@ Run `/skills reload` after creating or editing skills to ensure changes are pick 1. **Skills are automatic**: Copilot loads them when your prompt matches the skill's description 2. **Direct invocation**: You can also invoke skills directly with `/skill-name` as a slash command -3. **SKILL.md format**: YAML frontmatter (name, description, optional license) plus markdown instructions +3. **SKILL.md format**: YAML frontmatter (name, description, optional license, argument-hint) plus markdown instructions 4. **Location matters**: `.github/skills/` for project/team sharing, `~/.copilot/skills/` for personal use 5. **Description is key**: Write descriptions that match how you naturally ask questions +6. **Two ways to manage skills**: Use `copilot skill` from the terminal or `/skills` (shortcut: `/skill`) inside a session > 📋 **Quick Reference**: See the [GitHub Copilot CLI command reference](https://docs.github.com/en/copilot/reference/cli-command-reference) for a complete list of commands and shortcuts. diff --git a/06-mcp-servers/README.md b/06-mcp-servers/README.md index abac856c..bfbc7f80 100644 --- a/06-mcp-servers/README.md +++ b/06-mcp-servers/README.md @@ -924,6 +924,7 @@ These work when you're already inside `copilot`: | Command | What It Does | |---------|--------------| | `/mcp show` | Show all configured MCP servers and their status | +| `/mcp list` | Show currently attached MCP servers and their status; can be run while Copilot is working | | `/mcp add` | Interactive setup for adding a new server | | `/mcp edit ` | Edit an existing server configuration | | `/mcp enable ` | Enable a disabled server (persists across sessions) | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65d17bab..b22d6eb0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,6 +5,6 @@ Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great. -Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE.txt). +Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE). Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.