Skip to content

Commit 0868435

Browse files
committed
docs(develop-with-ai): address PR #8608 review feedback
Per Furkan: - Install only the aws-blocks skill: npx skills add aws/agent-toolkit-for-aws/skills --skill aws-blocks (verified the skills CLI supports -s/--skill). - Drop the hand-written CLAUDE.md/.cursor/.kiro rule dumps, which are easy to let drift out of date. Instead direct assistants to the official aws-blocks skill or the AGENTS.md that create-blocks-app scaffolds.
1 parent b01888f commit 0868435

1 file changed

Lines changed: 4 additions & 65 deletions

File tree

  • src/pages/[platform]/develop-with-ai/steering-files

src/pages/[platform]/develop-with-ai/steering-files/index.mdx

Lines changed: 4 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ If you see a "Plugin not found" error, refresh the marketplace index first with
141141
<Accordion title="Skills CLI (Cursor, and other tools)" headingLevel="4">
142142

143143
```bash
144-
npx skills add aws/agent-toolkit-for-aws/skills
144+
npx skills add aws/agent-toolkit-for-aws/skills --skill aws-blocks
145145
```
146146

147147
</Accordion>
@@ -158,72 +158,11 @@ Then launch Codex, run `/plugins`, and install the **aws-core** plugin.
158158

159159
For the full list of tools and setup options, see the [AWS agent toolkit](https://github.com/aws/agent-toolkit-for-aws) repository.
160160

161-
### Or add your own steering rules
161+
### Scaffold the project rules
162162

163-
If you prefer project-committed rules — or want to layer your team's own conventions on top of the skill — add a steering file with the guidelines below. The same content works across assistants; use the file format your tool expects.
163+
`create-blocks-app` can generate an `AGENTS.md` that documents the Blocks integration patterns for AI assistants, so in most cases you don't need to write steering rules by hand. To add AWS Blocks to your project, see [Add AWS Blocks to your Amplify project](/[platform]/build-a-backend/aws-blocks/get-started/).
164164

165-
<Accordion title="Claude (Code/Desktop)" headingLevel="3">
166-
167-
Add to your `CLAUDE.md` file in the project root:
168-
169-
```markdown title="CLAUDE.md"
170-
# AWS Blocks integration
171-
172-
This Amplify Gen 2 project uses AWS Blocks for backend capabilities.
173-
174-
- Define backend APIs, auth, and data in `aws-blocks/index.ts` using Building Blocks.
175-
- Use Building Blocks (`KVStore`, `DistributedTable`, `FileBucket`, etc.) for all persistence — never local files, in-memory arrays, or local databases.
176-
- Authenticate protected operations with `CognitoVerifier` and `requireAuth(context)`; it verifies the Amplify-issued Cognito token. Do not create a second user pool.
177-
- After changing the API surface, regenerate the client with `npm run blocks:generate-client`, then import and call the typed `api` (for example, `import { api } from 'aws-blocks'`). The JSON-RPC transport is invisible — do not build request payloads by hand.
178-
- Deploy and test Amplify and Blocks together with `npm run sandbox`.
179-
```
180-
181-
</Accordion>
182-
183-
<Accordion title="Cursor" headingLevel="3">
184-
185-
Create a rules file at `.cursor/rules/aws-blocks.mdc`:
186-
187-
```markdown title=".cursor/rules/aws-blocks.mdc"
188-
---
189-
description: AWS Blocks integration for Amplify
190-
globs:
191-
- "aws-blocks/**"
192-
- "amplify/**"
193-
---
194-
195-
# AWS Blocks integration
196-
197-
This Amplify Gen 2 project uses AWS Blocks for backend capabilities.
198-
199-
- Define backend APIs, auth, and data in `aws-blocks/index.ts` using Building Blocks.
200-
- Use Building Blocks for all persistence — never local files, in-memory arrays, or local databases.
201-
- Authenticate protected operations with `CognitoVerifier` and `requireAuth(context)`; it verifies the Amplify-issued Cognito token. Do not create a second user pool.
202-
- After changing the API surface, regenerate the client with `npm run blocks:generate-client`, then import and call the typed `api`. The JSON-RPC transport is invisible — do not build request payloads by hand.
203-
- Deploy and test Amplify and Blocks together with `npm run sandbox`.
204-
```
205-
206-
</Accordion>
207-
208-
<Accordion title="Kiro (IDE/CLI)" headingLevel="3">
209-
210-
Create a steering file at `.kiro/steering/aws-blocks.md`:
211-
212-
```markdown title=".kiro/steering/aws-blocks.md"
213-
# AWS Blocks integration
214-
215-
This Amplify Gen 2 project uses AWS Blocks for backend capabilities.
216-
217-
- Define backend APIs, auth, and data in `aws-blocks/index.ts` using Building Blocks.
218-
- Use Building Blocks for all persistence — never local files, in-memory arrays, or local databases.
219-
- Authenticate protected operations with `CognitoVerifier` and `requireAuth(context)`; it verifies the Amplify-issued Cognito token. Do not create a second user pool.
220-
- After changing the API surface, regenerate the client with `npm run blocks:generate-client`, then import and call the typed `api`. The JSON-RPC transport is invisible — do not build request payloads by hand.
221-
- Deploy and test Amplify and Blocks together with `npm run sandbox`.
222-
```
223-
224-
</Accordion>
225-
226-
To add AWS Blocks to your project in the first place, see [Add AWS Blocks to your Amplify project](/[platform]/build-a-backend/aws-blocks/get-started/).
165+
For authoritative, always-current guidance, point your assistant at the [`aws-blocks` skill](https://github.com/aws/agent-toolkit-for-aws/tree/main/skills/core-skills/aws-blocks) or an `AGENTS.md` rather than maintaining a separate copy of the rules, which can drift out of date as the Blocks APIs evolve.
227166

228167
## Tips for effective steering
229168

0 commit comments

Comments
 (0)