5.4 KiB
Cross-Platform AI Usage
You are here: AI Docs Home > Cross-Platform AI Usage
Instructions (Always-On Rules)
Instructions are repo-scoped rules that auto-apply based on file patterns. They are always on and do not need to be invoked.
Where they live:
- Repo instructions directory (for example, assets/instructions/)
- Editor or org-level instruction files when configured by your team
Agents.md
What It Is
Agents define a structured workflow so tasks are broken into clear steps, with explicit inputs and outputs.
How to Use It
- Read Agents.md.
- Choose a workflow that matches your task.
- Provide the inputs in a short, bounded request.
Example Request
Example prompt:
Goal: Improve readability in this module
Inputs: src/foo/Bar.kt, keep behavior the same
Output: A small refactor and a short summary
Verification: No tests needed
When to Use Agents vs Chat
- Use agents for multi-step tasks like refactors, doc audits, or migrations.
- Use chat for quick questions or one-off explanations.
Agents vs Skills (Quick Compare)
- Agents are full modes/personas that control behavior end-to-end. They can be stored in a repo or a user-level folder.
- Skills are focused workflows you load for specific tasks. They are typically installed globally via the approved skills directory.
Chat Modes In Copilot
Ask: Quick Q and A or summaries. Edit: Targeted file edits with constraints. Plan: Planning only, no edits yet. Agent: Multi-step work across files or tools.
Example prompts:
Ask: Explain this error message and list the top 3 likely fixes.
Edit: In this file, extract a helper function for validation and keep behavior the same.
Plan: Provide a 5-step plan to split this class into smaller components. Wait for approval.
Agent: Refactor the service layer, update tests, run the test task, and summarize results.
Request Template
Use this structure to get consistent results:
Goal: <one sentence>
Inputs: <files, constraints, context>
Output: <expected deliverable>
Verification: <tests or checks>
Prompting Patterns
Example prompts:
Refactors: Refactor this file to improve readability without changing behavior.
Tests: Add unit tests for this service. Keep the existing public API.
Debugging: Explain this error and list likely fixes in order.
Understanding code: Summarize what this module does and call out risks.
Prompting Anti-Patterns (And Fixes)
Common mistakes and better alternatives:
Example prompts:
Too broad: Fix everything in this project.
Better: Refactor this file to remove duplication. Do not change behavior.
Too vague: Make this code better.
Better: Improve naming and add comments only where logic is complex.
Missing inputs: Update the service to handle retries.
Better: Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
Example: Too Broad vs Scoped
Example prompts:
Too broad: Fix everything in this project.
Scoped: Refactor this file to remove duplication. Do not change behavior.
Plan-First Workflow
- Ask for a short plan.
- Approve or adjust the plan.
- Ask for targeted changes.
- Verify with tests or review.
Example Plan Request
Example prompt:
Provide a 5-step plan to refactor this module. Wait for approval before edits.
Starter Prompts (Copy/Paste)
Use these when you are not sure where to begin:
Example prompts:
Summarize this file in 5 bullets and list 2 risks.
Refactor this function to remove duplication. Keep behavior the same.
List tests I should add for this change.
Explain this error and propose the top 3 fixes.
Create a 5-step plan to split this class into smaller components.
Connecting Skills
- Use skills for tasks with known workflows.
- Combine multiple skills when a task spans domains.
- Pass concise context between steps to reduce repetition.
Efficiency Tips
- Keep prompts small and scoped.
- Reuse context from earlier steps instead of repeating it.
- Ask for summaries before asking for edits.
Example Summary Request
Example prompt:
Summarize the decisions so far in 6 bullets so I can start a new chat.
MCP (Model Context Protocol) - Cross-Platform Overview
MCP is an open standard that lets tools and agents interact with real systems. In plain language, MCP lets the assistant "do" things (like run builds or fetch logs) instead of just talking about them.
How MCP Helps In A Workflow
Think of MCP as a set of safe, structured buttons the assistant can press. You ask a question, the assistant calls a tool, and it returns a clear result.
Common MCP Use Cases (All Platforms)
- Run builds and tests
- Fetch logs or diagnostics
- Query project configuration
- Generate previews or reports
Example Workflow
- Ask the assistant to run a build.
- The MCP tool runs it and returns the result.
- You ask for a summary and next steps.
Example Prompt
Example prompt:
Use the build MCP tool to run the build and summarize any errors.
Where To Learn More
- iOS examples: see iOS Setup
- Android examples: see Android Setup
Next Steps
- If you need skills guidance, read Skills Library.
- For safety rules, read Governance, Privacy, and Policy.
- If setup is not working, follow Troubleshooting and FAQ.