# Cross-Platform AI Usage

You are here: [AI Docs Home](index.md) > Cross-Platform AI Usage

## Contents
- Instructions (Always-On Rules)
- Agents.md
- Agents vs Skills
- Prompting Patterns
- Prompting Anti-Patterns
- Plan-First Workflow
- Starter Prompts
- MCP Overview
- Next Steps

## 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/](../../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
1. Read [Agents.md](../../Agents.md).
2. Choose a workflow that matches your task.
3. Provide the inputs in a short, bounded request.

### Example Request
Example prompt:

```text
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:
```text
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:

```text
Goal: <one sentence>
Inputs: <files, constraints, context>
Output: <expected deliverable>
Verification: <tests or checks>
```

## Prompting Patterns
Example prompts:
```text
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:
```text
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:
```text
Too broad: Fix everything in this project.
Scoped: Refactor this file to remove duplication. Do not change behavior.
```

## Plan-First Workflow
1. Ask for a short plan.
2. Approve or adjust the plan.
3. Ask for targeted changes.
4. Verify with tests or review.

### Example Plan Request
Example prompt:
```text
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:
```text
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:
```text
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
1. Ask the assistant to run a build.
2. The MCP tool runs it and returns the result.
3. You ask for a summary and next steps.

### Example Prompt
Example prompt:
```text
Use the build MCP tool to run the build and summarize any errors.
```

### Where To Learn More
- iOS examples: see [iOS Setup](ios.md)
- Android examples: see [Android Setup](android.md)

## Next Steps
- If you need skills guidance, read [Skills Library](skills.md).
- For safety rules, read [Governance, Privacy, and Policy](governance.md).
- If setup is not working, follow [Troubleshooting and FAQ](troubleshooting.md).