# Customize Docs Agent for your organization

import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components';

Docs Agent learns your documentation style from your existing docs, but some conventions can't be inferred from your code or files alone — your preferred spelling, the purpose of each repository, which versions you support, or the terms your team standardizes on. Custom instructions let you give the agent this context once and have it apply the context to every session your organization runs.

Use this guide to add custom instructions and confirm the agent follows them.

## Before you begin

You need:

- An EkLine account with Docs Agent enabled
- At least one repository [connected to EkLine](/agent/github-app-setup/)

Any member of your organization can edit custom instructions.

## Add custom instructions

<Steps>
1. Log in to your [EkLine dashboard](https://ekline.io/dashboard).

2. Go to **Settings > Organization > Docs Agent**.

3. Find the **Custom instructions** section.

4. In the **Custom Instructions** field, enter the guidance you want the agent to follow. You can enter up to 5,000 characters.

5. Click **Refresh Docs Agent Instructions**. EkLine saves your instructions and regenerates the agent configuration. A progress indicator shows each stage, and a success message confirms when the update is complete.
</Steps>

The agent applies your instructions to every new session for your organization, whether you start it in the editor or trigger it from a [GitHub pull request](/agent/github-integration/), [GitLab merge request](/agent/gitlab-setup/), or [Slack](/agent/slack-bot/).

<Aside type="note">
Custom instructions apply to sessions started after you refresh. Refresh again whenever you change them so the agent picks up the update.
</Aside>

## What to include

Write custom instructions the way you would brief a new technical writer joining your team. Focus on context the agent can't get from reading your code:

- **Style preferences** — Spelling, capitalization, and voice. For example, `"Use American English spelling and sentence case for headings."`
- **Terminology** — Terms to prefer or avoid. For example, `"Refer to the product as EkLine, never Ekline or ekline."`
- **Repository context** — What each repository is for. For example, `"The api-gateway repo handles authentication and rate limiting; the web repo is the customer dashboard."`
- **Documentation structure** — How your docs are organized. For example, `"Place how-to guides in docs/guides and reference material in docs/reference."`
- **Versions and audience** — Which versions to document and who reads the docs. For example, `"Document v2 of the API only. Write for backend developers familiar with REST."`

<Aside type="tip">
Point the agent at a file in your repository for details that change often: `"Follow the writing conventions in docs/STYLE_GUIDE.md."` The agent reads the file during each session, so you don't have to duplicate its contents here.
</Aside>

### Example custom instructions

<Tabs>
  <TabItem label="Style and terminology">
    ```
    Use American English spelling and sentence case for headings.
    Refer to the product as EkLine. Use "sign in" as a verb and
    "sign-in" as an adjective. Write in the second person and
    active voice.
    ```
  </TabItem>
  <TabItem label="Repository context">
    ```
    The api-gateway repository handles authentication and rate
    limiting. The web repository is the customer dashboard. When
    documenting endpoints, link to the matching guide in the docs
    repository under docs/guides.
    ```
  </TabItem>
  <TabItem label="Structure and audience">
    ```
    Follow the Diataxis framework: tutorials, how-to guides,
    reference, and explanation each live in their own folder.
    Write for developers new to Kubernetes. Document v2 of the
    API only.
    ```
  </TabItem>
</Tabs>

## Verify the agent follows your instructions

<Steps>
1. Open the editor and start a new session.

2. Ask the agent to create or update a document — for example, `"Generate a README for this repository."`

3. Review the output for the conventions you specified. Check spelling, heading case, terminology, and structure against your instructions.
</Steps>

If the output doesn't reflect an instruction, make it more specific and refresh again. Short, concrete directions work better than long, general ones.

## How custom instructions relate to style learning

Custom instructions work alongside the agent's automatic style learning. The agent still analyzes your existing documentation for heading structure, code example conventions, terminology, and file organization. Custom instructions add the context the agent can't infer from your docs — and take precedence when your existing docs are inconsistent.

For more on how the agent learns your style, see [How does the agent know my documentation style?](/agent/reference/#how-does-the-agent-know-my-documentation-style) in the reference.

## Troubleshooting

### The Docs Agent settings page isn't available

Docs Agent access is granted on request. If you don't see **Settings > Organization > Docs Agent**, email **support@ekline.io** with your organization name to request access.

### The refresh fails or shows an error

The refresh clones your connected repositories to regenerate the agent configuration. If it fails:

- Verify that at least one repository is [connected to EkLine](/agent/github-app-setup/).
- Check that your instructions are within the 5,000-character limit.
- Try refreshing again. If the error persists, contact **support@ekline.io** with the error message shown.

### The agent ignores an instruction

- Make the instruction more specific and concrete.
- Point to a file in your repository instead of describing a long convention inline.
- Confirm you clicked **Refresh Docs Agent Instructions** after your most recent edit — changes apply only to sessions started after a refresh.

## Next steps

- [Create documentation](/agent/create/) — Generate READMEs, API references, and guides that follow your instructions.
- [Update and review](/agent/update-review/) — Keep docs in sync with code changes.
- [Docs Agent reference](/agent/reference/) — Supported file types, limits, and FAQ.