Good documentation helps developers succeed with Strands. We welcome contributions that make our docs clearer, more complete, or more helpful. Our documentation lives in the `site/` directory of the [Strands Harness SDK repository](https://github.com/strands-agents/harness-sdk).

## Agent skills

The repository ships agent skills in `.agents/skills/` that encode our documentation conventions, site components, and quality standards. If you’re using an AI coding assistant, activate these skills before making documentation changes. They produce output that matches our style, so you don’t have to internalize everything on this page.

| Skill | What it does |
| --- | --- |
| `docs-writer` | Drafts or rewrites documentation pages following site conventions |
| `docs-reviewer` | Reviews drafts for voice, structure, and terminology before PR |
| `docs-audit` | Assesses a page for quality, accuracy, and voice compliance |
| `docs-planner` | Identifies documentation gaps and prioritizes the backlog |

Use them by giving your agent a goal that references the skill:

```plaintext
Write a new doc page for the retry strategies feature. Use the docs-writer skill.
```

```plaintext
Audit the context management page for accuracy and voice issues. Use the docs-audit skill.
```

## What we accept

We’re looking for contributions that improve the developer experience. Documentation changes can range from small typo fixes to complete new guides.

| Type | Description |
| --- | --- |
| Typo fixes | Spelling, grammar, and formatting corrections |
| Clarifications | Rewording confusing sections |
| New examples | Code samples and tutorials |
| New guides | Complete tutorials or concept pages |
| Community extensions | Documentation for community-built packages |

## Setup

Run the docs locally to preview your changes as you work. The site is built with [Astro](https://astro.build/) and the [Starlight](https://starlight.astro.build/) theme.

```bash
# Clone the repository
git clone https://github.com/strands-agents/harness-sdk.git
cd harness-sdk/site

# Install dependencies
npm install

# Start the local development server
npm run dev

# Preview at http://localhost:4321
```

The development server automatically reloads when you save changes, so you can see your edits immediately.

## Submission process

The submission process varies based on the size of your change. Small fixes can go straight to PR, while larger changes benefit from discussion first.

1.  **Fork the repository** on GitHub
2.  **Create a branch** with a descriptive name like `docs/clarify-tools-usage` or `docs/fix-typo-agent-loop`
3.  **Make your changes** in your favorite editor
4.  **Preview locally** with `npm run dev` to verify formatting and links work correctly
5.  **Submit a pull request** with a clear description of what you changed and why

**For small changes** (typos, grammar fixes, minor clarifications), you can skip local preview and go straight to PR. We’ll catch any issues in review.

**For larger changes** (new guides, significant rewrites), we recommend opening a GitHub Discussion first to align on approach and scope.

## Style guidelines

We aim for documentation that teaches, not just describes. The reader should understand the “why” before the “how.”

### Voice and tone

Our documentation uses a collaborative, developer-peer voice. We write as knowledgeable colleagues helping you succeed.

| Principle | Example | Why |
| --- | --- | --- |
| Use “you” for the reader | ”You create an agent by…” not “An agent is created by…” | Direct and personal |
| Use “we” collaboratively | ”Let’s install the SDK” not “Install the SDK” | Creates partnership |
| Active voice, present tense | ”The agent returns a response” not “A response will be returned” | Clear and immediate |
| Explain why before how | Start with the problem, then the solution | Builds understanding |

### Writing style

Keep prose tight and focused. Readers scan documentation looking for answers.

| Do | Don’t |
| --- | --- |
| Keep sentences under 25 words | Write long, complex sentences with multiple clauses |
| Use “to create an agent, call…” | Use “in order to create an agent, you should call…” |
| Include code examples | Describe without showing |
| Use tables for comparisons | Use long bullet lists for structured data |
| Add lead-in sentences before lists | Jump directly into bulleted lists |

### Code examples

Code examples show developers exactly what to do, so always test them before submitting.

-   Test all code: every example must actually work
-   Include both languages: provide Python and TypeScript when both are supported
-   Start simple: show the minimal example first, then add complexity
-   Add comments: explain non-obvious parts
-   Use realistic names: avoid foo/bar, use descriptive names

(( tab "Python" ))
```python
# Good: Start simple
from strands import Agent
agent = Agent()
agent("Hello, world!")

# Then show configuration
from strands import Agent

agent = Agent(
    system_prompt="You are a helpful assistant."
)
agent("What's the weather like?")
```
(( /tab "Python" ))

(( tab "TypeScript" ))
```typescript
import { Agent } from '@strands-agents/sdk'

// Good: Start simple
const agent = new Agent()
await agent.invoke('Hello, world!')

// Then show configuration
const configuredAgent = new Agent({
  systemPrompt: 'You are a helpful assistant.',
})
await configuredAgent.invoke("What's the weather like?")
```
(( /tab "TypeScript" ))