# Cross-Platform AI Usage

## 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

```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.

### 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
- 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."

### Example: Too Broad vs Scoped
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
"Provide a 5-step plan to refactor this module. Wait for approval before edits."

## 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
"Summarize the decisions so far in 6 bullets so I can start a new chat."