Guides
Write your own instructions
Change what the agents do in your repository, with files in the folders .agents and .claude.
After this guide, the agents follow your own instructions for your repository, instead of the platform's.
Who can do it: a person who can change the default branch of the repository on GitHub. No role in the app is needed.
Before you start
You do not need any of these files. Without them, the agents use the platform's own instructions.
The agents read the files from the default branch of the repository. A file on another branch does nothing until it is merged.
Review a change to these files like a change to your code. It changes what every later job of the agents does. The agents themselves never change these files.
The platform's own limits stay in force, whatever a file says. The agents never see your keys, never change the paths that are always blocked, and use only the tools the platform allows.
Instructions for one kind of job
- Make a file
.agents/prompts/<name>.mdin your repository, with the name of the kind of job. - Write the whole instructions for that kind of job in it. The file replaces the platform's instructions for that kind of job. It does not add to them.
- Merge it into the default branch.
The names:
| Name | The job |
|---|---|
review | The Product analytics review |
error-triage | Error triage |
plan | The plan for a suggestion |
implement | Making a change |
revise | Correcting a change, after you ask for a change |
pr-review | The second reading of a change by a second AI |
code-review | The PR reviewer |
ci-fix | The CI fixer |
issue-triage | Issue triage |
docs-update | The Docs updater |
ask | A question in Chat or Telegram |
Clarity queries
The Collector (Clarity) reads which numbers to collect from .agents/clarity-queries.txt. The collector does not work without this file. See Connect analytics and Sentry.
Write one query per line: a name, a space, then the Clarity dimensions, separated by commas. A line that starts with # is a comment. A name has letters, digits, dots, dashes and underscores. For example:
# name, then dimensions
by-device Device
by-page-and-browser URL,BrowserClarity allows 10 requests a day, and each line is one request. Keep the list short.
The steps of the analytics review and the error triage
The Product analytics review and Error triage each follow a list of steps. To change it, add one of these files:
.claude/skills/analytics-review/SKILL.mdfor the Product analytics review;.claude/skills/error-triage/SKILL.mdfor Error triage.
Without the file, the agent follows the platform's own steps.
A review across every repository
In a product with several repositories, a review that reads every repository uses the file of the main repository only. The files in the other repositories are not read for it. See A product with several repositories.
For the instructions of one kind of job, a repository that has no file of its own uses the file of the main repository.
What you see when it worked
The next job of that kind follows your file. Read its result on the Activity page, or the report under Documents.
More
- Instruction files: every file the agents read, and the tool rules for each kind of job.
- Repository rules and privacy: the paths the agents never change.
- When something does not work.