agency-swarm-cn-git/.cursor/rules/writing-docs.mdc

---
alwaysApply: true
---

When writing or improving documentation for Agency Swarm, your primary goal is clarity for the target reader: show the information they need to complete the task, with enough context to avoid confusion.

# Agency Swarm Documentation Writing Rules

- Write documentation in an easy to understand conversational language.
- Use simple language and clear terms.
- Docs should be easily readable by an 8th grader.
- Be concise, but keep full sentences and transitions when they are needed for readability.
- Make documentation actionable. Place code snippets at the top so users can easily copy and paste them. Provide only essential context above the code. Move any complex or detailed explanations to the end of the page.
- The more important the information is, the higher it should be on the page.
- Highlight the important parts by using bold, components, etc.
- Hide complexity under tabs, dropdowns, etc.
- Split pages into sub pages if needed. Use ~150 visible lines as a readability target, not a hard limit. Collapsed content (for example accordions) does not count toward this target.

## Release Notes

Use these rules for release notes so the intro stays readable and every claim stays tied to a shipped change.

- Write the opening paragraph and each section intro for non-technical readers first. In one or two sentences, say what changed and why it matters in plain English.
- Ground every phrase in a concrete change from the repo or release diff. If a phrase cannot be tied to a command, API, capability, limit, or fix, delete it.
- Prefer plain verbs and nouns like `start`, `open`, `run`, `set up`, `use`, and `fix`.
- Avoid vague opener words like `documented`, `surface`, `workflow`, `path`, and `behavior` unless the exact term is required for accuracy.
- Keep the intro broad and easy to read, then let the bullets carry the exact commands, APIs, models, limits, PR numbers, and contributor names.
- Group sections by reader value, not by implementation layer.
- Do not present internal policy or agent-rule changes as public docs. If they must be included, label them as internal maintenance and keep them brief.

# Mintlify Components Reference

You can utilize various components from mintlify:

## Accordion

Collapsible sections for optional or detailed content:

```mdx
<Accordion title="Advanced Options" defaultOpen={false}>
  Content here
</Accordion>
```

## Tabs

Switch between different code examples or content:

```mdx
<Tabs>
  <Tab title="Python">Python code</Tab>
  <Tab title="JavaScript">JS code</Tab>
</Tabs>
```

## Cards

Highlight key links or concepts:

```mdx
<Card title="Getting Started" icon="rocket-launch" href="/quickstart">
  Start building your first agency
</Card>
```

## Steps

Display sequential instructions:

```mdx
<Steps>
  <Step title="Install">Install the package</Step>
  <Step title="Configure">Set up your config</Step>
</Steps>
```

## CodeGroup

Group related code examples:

````mdx
<CodeGroup>
  ```python example.py
  # Python version
````

```javascript example.js
// JS version
```

</CodeGroup>
```

## API Components

For API documentation:

```mdx
<ParamField param="name" type="string" required>
  Parameter description
</ParamField>

<ResponseField name="status" type="string">
  Response field description
</ResponseField>
```

# Instructions

## Before Starting

If style is unclear, review one or more of these examples:

- [Tools](docs/core-framework/tools/overview.mdx)
- [Agents](docs/core-framework/agents/overview.mdx)
- [Agencies](docs/core-framework/agencies/overview.mdx)
- [Communication Flows](docs/core-framework/agencies/communication-flows.mdx)

Use these examples as guidance, not strict templates.

## Updating Existing Pages

1. Analyze the feedback provided by the user and determine which specific sections you need to update.
   - If there is a lot of feedback, create a to-do list for yourself and break it down.
2. Only update the required parts, do not add anything unrequested. Perform minimal changes, keep everything unaffected by feedback as is. Only update the parts and the pages that are explicitly requested.
3. If asked to move the page, keep consistent folder and file structure, matching the structure in the `./docs/docs.json` file.
4. Ask the user to review the changes and provide feedback.

## Writing New Pages

1. Analyze the information or the relevant code provided by the user.
   - If critical information is missing, ask only the minimum questions needed to proceed.
   - For example:
     - What is the use case for this?
     - Where can I see relevant files?
     - Do you have any example code snippets?
     - Why did you create this feature in the first place?
     - What does the user have to know before they can start using it?
     - etc...
2. Create a new page reference in the `./docs/docs.json` file in the appropriate group and sub group.
   - If it's unclear where to place the page, ask the user for clarification.
   - Make sure the folder structure in docs folder matches the structure in the `./docs/docs.json` file.
3. Write the page content using the same path, following all the rules above.
4. Ask the user to review the page and provide feedback.
5. Implement any adjustments as needed. See "Updating Existing Pages" section below.

# Additional Notes

-

# References

- [Mintlify Documentation](https://www.mintlify.com/docs/llms.txt) - Check if you need clarification about how mintlify works or looking for any other components.