You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .agents/skills/agenta-package-practices/SKILL.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -134,6 +134,8 @@ via `ModalFooter`, theme integration.
134
134
135
135
## Style utilities and presentational components
136
136
137
+
When adding or changing UI elements, implement appearance and interaction states for both light and dark themes, and verify both before considering the work complete.
description: Regenerate and refresh the curated agent model catalog (the label/description/pricing/ratings behind the agent model picker). Use when the pinned @earendil-works/pi-ai version bumps, when a Claude Code build changes its accepted alias set, or before a release when the curated Claude/Pi facts (lineup, pricing, ratings) need refreshing from current public sources. Owns the data files under sdks/python/agenta/sdk/agents/data/; never edits capabilities.py logic.
Copy file name to clipboardExpand all lines: .agents/skills/write-docs/SKILL.md
+138Lines changed: 138 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,144 @@ user-invocable: true
9
9
10
10
A short, living set of rules for writing documentation in this repo. Update as we learn what works.
11
11
12
+
## 0. Write for a reader in a situation
13
+
14
+
This rule governs every other rule below. Every failure in a doc review traces back to breaking it.
15
+
16
+
Your reader is a **stranger with a job to do**. They are not your teammate, they did not read the PR, they do not know the codebase, and they do not care about your reasoning. They arrived with a situation and a question. Serve that, nothing else.
17
+
18
+
Some readers are agents, some are humans. Write for both: an agent needs unambiguous structure, a human needs to find their case fast. Neither needs your narration.
19
+
20
+
### The four beats
21
+
22
+
For anything non-trivial (a troubleshooting entry, a decision, a procedure with branches), give the reader these in order. Do not overdo it on simple content.
23
+
24
+
1.**Context.** What is the situation? Stated plainly, so I can tell whether I am in it.
25
+
2.**Relevance.** Is this me? Do I need to act? Let me self-select out fast.
26
+
3.**Instructions.** Exactly what to run or change. Concrete, copy-pasteable.
27
+
4.**References.** Links to go deeper, if it is complicated.
28
+
29
+
A section that says "enable the tunnel profile" without telling me *how* has skipped beat 3. A warning that does not tell me whether it applies to me has skipped beats 1 and 2.
30
+
31
+
### Never assume things about the reader
32
+
33
+
Do not tell readers what they think, what they usually get wrong, or what their first question is. You do not know them, and the sentence serves you, not them.
34
+
35
+
- BAD: "This is the part teams usually get wrong."
36
+
- BAD: "This is the first question a self-hosting community asks."
37
+
- BAD: "You probably want X."
38
+
- GOOD: State the fact. Let them decide if it is their case.
39
+
40
+
### No opinions, no value judgments
41
+
42
+
Docs state facts and give instructions. They do not give advice you were not asked for, and they do not editorialize.
43
+
44
+
- BAD: "Keep CPU and memory generous."
45
+
- BAD: "This is the right way to do it."
46
+
- GOOD: "The default is 2 CPU / 4 GB. To change it, set X."
47
+
48
+
If a constraint is real, state it as a constraint ("the idle TTL must be below AUTOSTOP, or Daytona stops a sandbox the runner still holds"). That is a fact, not an opinion.
49
+
50
+
### Only the reader's problem belongs on the page
51
+
52
+
Cut anything that is not the reader's concern in *their* situation.
53
+
54
+
- In a how-to for running agents on Daytona, the **code evaluator's** sandbox is not the reader's problem. It confuses them. If the fact matters, it belongs in reference.
55
+
- Do not pre-empt failure modes the reader cannot hit. If you just told them to run the snapshot recipe, do not then warn "if the image is missing Pi…". They followed your instructions. It will not be missing.
56
+
57
+
Ask of every sentence: **in the situation this page is for, does the reader need this?** If not, delete it or move it to reference.
58
+
59
+
### Parallel things get parallel structure
60
+
61
+
If two options exist (Daytona and local; Compose and Helm), give them **mirrored sections with the same sub-structure, in the same order, on every page**. A reader learns the shape once and then navigates by it.
62
+
63
+
- Nest correctly. "What crosses into the Daytona sandbox" belongs **under** Daytona, not floating at the top level.
64
+
- If you write a subsection for one option, write the matching one for the other, or explicitly say it does not apply.
65
+
- Lead with the option you want most people to use.
66
+
67
+
### An instruction without a concrete example is not an instruction
68
+
69
+
"Add your dependencies" tells the reader nothing. Name a plausible thing and show the line. The
70
+
reader adapts an example far faster than they invent one from a description.
71
+
72
+
- BAD: "Add your dependencies to the recipe."
73
+
- GOOD: "Add your dependencies to `dockerfile_commands`. For example, the `gh` CLI and Chromium: `RUN apt-get install -y gh chromium`."
74
+
- GOOD: "Mount a repository checkout so agents can work on it: `- /srv/repos/my-service:/agenta/workspaces/my-service:rw`. Use `:ro` when they should only read it."
75
+
76
+
### Use the precise word, not the dramatic one
77
+
78
+
Vague adjectives, especially security ones, make the reader guess. Say the condition that is
79
+
actually true.
80
+
81
+
- BAD: "Use Daytona when your deployment is exposed." (Exposed to what? Does that include me?)
82
+
- GOOD: "Use Daytona when more than one person can start runs on the deployment."
83
+
- BAD: "Local runs are not safe."
84
+
- GOOD: "Local runs are not isolated from each other. One user's agent can read another's files."
85
+
86
+
### A pointer is a sentence, not a section
87
+
88
+
If the answer is "go read that other page", write one sentence with the link where the reader hits
89
+
the question. Do not give it a heading and three paragraphs of setup. A section promises content.
90
+
91
+
### Slugs exist to preserve URLs
92
+
93
+
Add a `slug:` to a page's frontmatter only when the file moved and the old public URL must keep
94
+
working, or when the natural path is wrong. Never add one just because other pages have one.
95
+
96
+
### Verify every instruction against the thing it instructs
97
+
98
+
Prose discipline is not enough. An instruction you did not check is a lie with good grammar, and it
99
+
costs the reader an afternoon.
100
+
101
+
Before you write "set X in your values file", open the chart and confirm the key exists. Before you
102
+
write "add a `COPY` step", confirm the build has a local context. Before you name an env var,
103
+
confirm the code reads it. Before you claim "everything else is documented above", go count.
104
+
105
+
Real failures caught in review, all of which read fluently:
106
+
107
+
- BAD: "For Helm, add the volume to the runner pod in your values file." The chart renders **no**
108
+
user volumes and `values.schema.json` has no volumes key. The instruction is impossible.
109
+
- BAD: "Copy files in with a `COPY` step." The snapshot recipe uses `dockerfile_commands()` with no
110
+
local build context, so `COPY` cannot work. `RUN git clone` can.
111
+
- BAD: "Every other variable the runner reads is documented above." It reads about forty more.
112
+
113
+
If you cannot verify a claim, do not write it. Cut it, or go read the code.
114
+
115
+
### Prerequisites are the universal minimum; edge cases go in troubleshooting
116
+
117
+
A prerequisites list is what EVERY reader needs before they start. Do not pad it with the obvious,
118
+
and do not front-load setup that only a subset hits. If a problem bites only some readers, put it in
119
+
troubleshooting keyed to the symptom they will actually see, so the rest never read it.
120
+
121
+
- BAD (prerequisite): "Docker installed on your machine." Obvious. Cut it, or make it one line.
122
+
- BAD (prerequisite): three paragraphs on `/var/run/docker.sock` ownership and `usermod -aG docker`
123
+
before the reader can run anything. Most readers already have daemon access.
124
+
- GOOD (troubleshooting): "**`permission denied ... /var/run/docker.sock`** — your user cannot reach
125
+
the Docker daemon. Run as root, use `sudo`, or `sudo usermod -aG docker $USER` then open a new
126
+
shell. (docker-group membership is root-equivalent on the host.)"
127
+
128
+
### Reuse the patterns that already exist
129
+
130
+
Before inventing a layout, look at how the rest of the docs do it. Use the existing Docusaurus components: `:::info`, `:::warning`, `:::tip`, collapsibles. Do not invent a new troubleshooting format per page. Consistency is what lets a reader skim.
131
+
132
+
Use an admonition for a genuine warning or aside. Do not smuggle a caveat into body prose.
133
+
134
+
### Titles are plain labels, not sentences
135
+
136
+
A heading is a signpost. "Sandbox isolation and security", not a clause or a claim. If a reader cannot tell what is under a heading from the heading alone, rename it.
137
+
138
+
### Overview pages are indexes, not essays
139
+
140
+
An overview answers "where do I start and what applies to me". It is a short, high-level map with links, not a prose introduction to the product and not a restatement of the sidebar. Assume the reader already knows what Agenta is.
141
+
142
+
### Comments in config examples are for humans
143
+
144
+
Env examples get commented for a human skimming them, not for exhaustive machine documentation.
145
+
146
+
- Comment the **non-obvious**: defaults, units, constraints, what breaks.
147
+
- Do **not** comment the obvious. `AGENTA_RUNNER_CONCURRENCY_LIMIT` does not need "maximum concurrent runs".
148
+
- Long explanations belong in the reference page, not in every env file.
149
+
12
150
## 1. Pick the doc type first (Diátaxis)
13
151
14
152
Before writing, decide which of the four types you are writing. Don't mix them in one page.
0 commit comments