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
An essential aspect of becoming productive while working with agents is to _blend them with code_. Your agents need to adapt to the codebase, and your codebase needs to adapt to the agents. For example, you might not necessarily like the commit message that the agent has just produced.
14
+
An essential aspect of becoming productive while working with agents is to
15
+
_blend them with code_.
16
+
Your agents need to adapt to the codebase, and your codebase needs to adapt to
17
+
the agents.
18
+
For example, you might not necessarily like the commit message that the agent
19
+
has just produced.
12
20
13
-
One way to steer agents toward doing the right things is to have an `AGENTS.md` file in the repository root. This file is read by the agent in each thread.
21
+
One way to steer agents toward doing the right things is to have an `AGENTS.md`
22
+
file in the repository root.
23
+
This file is read by the agent in each thread.
14
24
15
25
:::note
16
-
This file is standardized and supported by most agent harnesses (except Claude Code). There are also harness-specific mechanisms, like `CLAUDE.md` or <ExternalLinkhref="https://cursor.com/docs/context/rules">Cursor Rules</ExternalLink>.
26
+
This file is standardized and supported by most agent harnesses (except Claude Code).
27
+
There are also harness-specific mechanisms, like `CLAUDE.md`
28
+
or <ExternalLinkhref="https://cursor.com/docs/context/rules">Cursor Rules</ExternalLink>.
17
29
:::
18
30
19
31
:::tip
20
-
Don’t use the `/init` command of your harness of choice (which is meant to set up such rules files). It tends to produce documents that bring little meaningful value.
32
+
Don’t use the `/init` command of your harness of choice (which is meant to set
33
+
up such rules files).
34
+
It tends to produce documents that bring little meaningful value.
21
35
:::
22
36
23
37
<Steps>
24
38
25
-
1. Write a minimal `AGENTS.md` file. The goal is just to steer the agent to do the right thing every time. Here is <ExternalLinkhref="https://github.com/mkaput">Marek Kaput</ExternalLink>’s example template:
39
+
1. Write a minimal `AGENTS.md` file.
40
+
The goal is just to steer the agent to do the right thing every time.
41
+
Here is <ExternalLinkhref="https://github.com/mkaput">Marek Kaput</ExternalLink>’s
42
+
example template:
26
43
27
44
:::tip[Claude Code]
28
-
In Claude Code, instead of telling the agent to run linters/typecheckers via AGENTS.md rules, set them up as <ExternalLinkhref="https://code.claude.com/docs/en/hooks">hooks</ExternalLink>. Hooks run automatically after each file edit, so the agent gets instant feedback without burning context on lint/typecheck output from explicit tool calls.
45
+
In Claude Code, instead of telling the agent to run linters/typecheckers via
46
+
AGENTS.md rules, set them up as <ExternalLinkhref="https://code.claude.com/docs/en/hooks">hooks</ExternalLink>.
47
+
Hooks run automatically after each file edit, so the agent gets instant
48
+
feedback without burning context on lint/typecheck output from explicit tool
49
+
calls.
29
50
:::
30
51
31
52
```md
32
53
# [Project name]
33
54
34
55
## Rules
35
56
36
-
- you may be running in parallel with other agents; cooperate to avoid conflicts, but avoid committing changes made by others
57
+
- you may be running in parallel with other agents; cooperate to avoid conflicts,
58
+
but avoid committing changes made by others
37
59
- add test coverage for new logic and regression fixes where practical
38
60
- run `npm lint` to format code and run linters; run `npm test` to run tests
39
61
- ignore any backward compatibility - break stuff everywhere if needed
@@ -46,19 +68,28 @@ Don’t use the `/init` command of your harness of choice (which is meant to set
46
68
47
69
## Dev environment tips
48
70
49
-
- Use `pnpm dlx turbo run where «project_name»` to jump to a package instead of scanning with `ls`.
50
-
- Run `pnpm install --filter «project_name»` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
51
-
- Use `pnpm create vite@latest «project_name» -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
52
-
- Check the name field inside each package's package.json to confirm the right name - skip the top-level one.
71
+
- Use `pnpm dlx turbo run where «project_name»` to jump to a package instead
72
+
of scanning with `ls`.
73
+
- Run `pnpm install --filter «project_name»` to add the package to your workspace
74
+
so Vite, ESLint, and TypeScript can see it.
75
+
- Use `pnpm create vite@latest «project_name» -- --template react-ts` to spin
76
+
up a new React + Vite package with TypeScript checks ready.
77
+
- Check the name field inside each package's package.json to confirm the
78
+
right name - skip the top-level one.
53
79
54
80
## Testing instructions
55
81
56
82
- Find the CI plan in the .github/workflows folder.
57
-
- Run `pnpm turbo run test --filter «project_name»` to run every check defined for that package.
58
-
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
59
-
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "«test name»"`.
83
+
- Run `pnpm turbo run test --filter «project_name»` to run every check
84
+
defined for that package.
85
+
- From the package root you can just call `pnpm test`. The commit should pass
86
+
all tests before you merge.
87
+
- To focus on one step, add the Vitest pattern:
88
+
`pnpm vitest run -t "«test name»"`.
60
89
- Fix any test or type errors until the whole suite is green.
61
-
- After moving files or changing imports, run `pnpm lint --filter «project_name»` to be sure ESLint and TypeScript rules still pass.
90
+
- After moving files or changing imports, run
91
+
`pnpm lint --filter «project_name»` to be sure ESLint and TypeScript rules
92
+
still pass.
62
93
- Add or update tests for the code you change, even if nobody asked.
63
94
64
95
## PR instructions
@@ -67,7 +98,8 @@ Don’t use the `/init` command of your harness of choice (which is meant to set
67
98
- Always run `pnpm lint` and `pnpm test` before committing.
68
99
```
69
100
70
-
It is rather important to keep this file relatively short but dense in crucial hints. If a piece of information is one `ls` or `cat` call away, it can be skipped.
101
+
It is rather important to keep this file relatively short but dense in crucial hints.
102
+
If a piece of information is one `ls` or `cat` call away, it can be skipped.
71
103
72
104
Below, you can see an example of what **NOT** to include.
73
105
@@ -116,21 +148,41 @@ Don’t use the `/init` command of your harness of choice (which is meant to set
116
148
</Steps>
117
149
118
150
:::tip
119
-
As your codebase and AGENTS.md grow, it will make sense to move chunks of that file into either skills or separate files in the `docs/` directory, while AGENTS.md becomes mostly a table of contents.
151
+
As your codebase and AGENTS.md grow, it will make sense to move chunks of that
152
+
file into either skills or separate files in the `docs/` directory, while
153
+
AGENTS.md becomes mostly a table of contents.
120
154
:::
121
155
122
156
## Skills
123
157
124
-
Agent Skills is an open standard for extending AI agents with specialized capabilities. Skills package domain-specific knowledge and workflows that agents can use to perform specific tasks.
158
+
Agent Skills is an open standard for extending AI agents with specialized
159
+
capabilities.
160
+
Skills package domain-specific knowledge and workflows that agents can use to
161
+
perform specific tasks.
162
+
163
+
We can’t tell you upfront what skills you might need without knowing what
164
+
you’re working on (because skills are domain-specific).
165
+
Fortunately, you don’t need to worry about where to put skill files or how each
166
+
harness expects them to be structured.
125
167
126
-
We can’t tell you upfront what skills you might need without knowing what you’re working on (because skills are domain-specific). Fortunately, you don’t need to worry about where to put skill files or how each harness expects them to be structured. The interactive CLI `npx skills` handles all of that — it pulls skills from the <ExternalLinkhref="https://skills.sh/">skills.sh</ExternalLink> directory and installs them in the right format for 40+ agent harnesses, including Claude Code, Cursor, Amp, Codex, Gemini CLI, GitHub Copilot, and many more.
168
+
The interactive CLI `npx skills` handles all of that - it pulls skills from
169
+
the <ExternalLinkhref="https://skills.sh/">skills.sh</ExternalLink>
170
+
directory and installs them in the right format for 40+ agent harnesses,
171
+
including Claude Code, Cursor, Amp, Codex, Gemini CLI, GitHub Copilot, and many more.
127
172
128
173
129
174
130
175
:::caution
131
-
Before you try a new skill, always read its entire source and think about its security considerations. Skills are a powerful mechanism partly because they can be insecure. The surrounding ecosystem is still very young, and many skill-based attacks are happening in the wild.
176
+
Before you try a new skill, always read its entire source and think about its
177
+
security considerations.
178
+
Skills are a powerful mechanism partly because they can be insecure.
179
+
The surrounding ecosystem is still very young, and many skill-based attacks are
180
+
happening in the wild.
132
181
:::
133
182
134
183
:::tip
135
-
Skills are meant to be amended by you or your agent to tailor to your project, machine, and taste. Don’t be afraid to fork a skill. If the “upstream” skill is updated, tell your agent to update your fork.
184
+
Skills are meant to be amended by you or your agent to tailor to your project,
185
+
machine, and taste.
186
+
Don’t be afraid to fork a skill.
187
+
If the “upstream” skill is updated, tell your agent to update your fork.
0 commit comments