Repository navigation
🤖 Add Claude skills - #2746
🤖 Add Claude skills#2746AntoLC wants to merge 7 commits into
Conversation
8794645 to
0d97bf3
Compare
0d97bf3 to
acca8cb
Compare
|
@AntoLC Claude doesn't have a monopolyy on skills, can we use a more generic terminology moving forward. Smthg like AI Skills, or AI agent skills. |
Ovgodd
left a comment
Ovgodd
left a comment
There was a problem hiding this comment.
I like it !
As talked together I will improve, made little change in the docs-accessibility-review skill in another PR ! but this is very good
Yes Claude has the monopoly on these skills, because it is Claude skills that are added, for Cursor or others the syntax is lightly different, and they have to be in different folder in order to work correctly, we focus on Claude in a first PR, contributors are allowed to complete depend their need. |
| The easiest way to start is using the Claude `/docs-start` skill. | ||
|
|
||
| It checks what is already built, stale or running, then runs only the Make | ||
| targets needed: `make bootstrap` on a first run, the rebuild of the images | ||
| whose dependencies changed after a pull, or just `make run`. | ||
|
|
||
| Otherwise, bootstrap everything with GNU Make: |
There was a problem hiding this comment.
Oh no I don't think we should change that. Here you clearly mention that you should use agent first and I don't think we want to go this way.
There was a problem hiding this comment.
😅 I think it is the easiest way to start now ^^, but yes the world is maybe not ready and Claude maybe too opinionated.
I made a fixup, I proposed it as a alternative at the end of the paragraphe, tell me if you find that more appropriate or if we should just remove it.
Ovgodd
left a comment
Ovgodd
left a comment
There was a problem hiding this comment.
I like it overall! Just added a few small clarifications around focus management, screen reader announcements and WCAG criteria. Looks good to me otherwise!
Agents working on Docs kept rediscovering the same project specifics: Makefile targets, backend test setup, E2E helpers, review focus points. Version the skills for backend work, E2E tests, PR reviews and accessibility reviews so that every contributor gets them. .claude/ was ignored as a whole: ignore only its content, except the skills folder, and keep the local-* skills out of git, as they hold personal workflows.
The skill runs a read-only check first (check-stack.sh) that reports missing or stale images, dependency volumes older than their image, pending migrations and a local yarn dev on :3000, then suggests only the Makefile targets that are needed. The agent will then propose only the necessary Makefile targets based on the check results.
Agents spent a large share of their tokens rediscovering the same things: reading huge files whole, loading generated files, running the full lint and test suites to check a one-line change. The "Working efficiently" section points them to the matching skill, to grep-then-read for the big backend files, to the files never worth reading, and to narrow checks first. The "Knowledge feedback" section makes agents record what they verified and would have needed at the start of a task, in the narrowest place that fits (this file, a skill, a README), so the next task starts from it. As AGENTS.md is loaded in every session, it also asks them to keep it lean: move area-specific lines to their skill, drop stale ones, and merge skills that trigger on the same request.
Maintainers triage a long issue list: an issue must be understood from its title and fixed without a round of questions. The skill checks for duplicates, keeps the body under 5 lines, points at the code with permalinks pinned on a commit of main so they survive later changes, and ends with a suggested fix. It creates the issue through the REST API, which also sets the issue type that older gh versions cannot. While on a task, agents sometimes come across a real bug, a security issue or a clear improvement unrelated to it. The new "Incidental findings" section of AGENTS.md makes them report it at the end, without widening the task, and offer to file it with the skill under the "AI generated" label.
acca8cb to
f09cb2d
Compare
lunika
left a comment
lunika
left a comment
There was a problem hiding this comment.
Don't know where it should be added but add an instruction to be short concise in the comments in the code it adds
| For exceptional commands not covered by the Makefile, use: | ||
|
|
||
| ```bash | ||
| docker compose exec app-dev <command> |
There was a problem hiding this comment.
| docker compose exec app-dev <command> | |
| ./bin/manage <command> |
| For example: | ||
|
|
||
| ```bash | ||
| docker compose exec app-dev python manage.py check |
There was a problem hiding this comment.
| docker compose exec app-dev python manage.py check | |
| ./bin/manage check |
| ## Running Django management commands | ||
|
|
||
| The Makefile runs management commands through an ephemeral `app-dev` container with the expected development environment. | ||
|
|
||
| Available project commands include: | ||
|
|
||
| ```bash | ||
| make migrate | ||
| make makemigrations | ||
| make shell | ||
| make dbshell | ||
| make superuser | ||
| ``` | ||
|
|
||
| Use these instead of directly invoking `python manage.py` from the host. | ||
|
|
||
| If an uncommon management command is needed, follow the same project convention: | ||
|
|
||
| ```bash | ||
| docker compose run --rm app-dev python manage.py <command> |
There was a problem hiding this comment.
can be removed, you repeat the same thing
| Prefer: | ||
|
|
||
| ```bash | ||
| make test |
There was a problem hiding this comment.
| make test | |
| ./bin/pytest -n auto |
The AGENTS.md file also tells to use ./bin/pytest, it is much more flexible to execute tests
| This currently runs backend tests in parallel. | ||
|
|
||
| Equivalent explicit command: | ||
|
|
||
| ```bash | ||
| make test-back-parallel | ||
| ``` | ||
|
|
||
| The project uses pytest with automatic parallel execution for the complete suite. | ||
|
|
||
| ### Run specific tests | ||
|
|
||
| Use: | ||
|
|
||
| ```bash | ||
| make test-back <pytest arguments> | ||
| ``` | ||
|
|
||
| Examples: | ||
|
|
||
| ```bash | ||
| make test-back tests/test_documents.py | ||
| ``` | ||
|
|
||
| ```bash | ||
| make test-back tests/test_documents.py::test_example | ||
| ``` | ||
|
|
||
| ```bash | ||
| make test-back -k permission | ||
| ``` |
There was a problem hiding this comment.
| This currently runs backend tests in parallel. | |
| Equivalent explicit command: | |
| ```bash | |
| make test-back-parallel | |
| ``` | |
| The project uses pytest with automatic parallel execution for the complete suite. | |
| ### Run specific tests | |
| Use: | |
| ```bash | |
| make test-back <pytest arguments> | |
| ``` | |
| Examples: | |
| ```bash | |
| make test-back tests/test_documents.py | |
| ``` | |
| ```bash | |
| make test-back tests/test_documents.py::test_example | |
| ``` | |
| ```bash | |
| make test-back -k permission | |
| ``` | |
| This script allows to use all `pytest` options available | |
| For example, run a specific test file/directory | |
| ```bash | |
| bin/pytest -n auto path/to/test |
Or run a single test
bin/pytest -n auto path/to/test.py::TestClass::test_method| and: | ||
|
|
||
| ```bash | ||
| make test-back <relevant tests> |
There was a problem hiding this comment.
| make test-back <relevant tests> | |
| ./bin/pytest <relevant tests> |
| For significant backend changes, also consider: | ||
|
|
||
| ```bash | ||
| make test |
There was a problem hiding this comment.
| make test | |
| ./bin/pytest -n auto |
|
I found this project https://www.npmjs.com/package/skills |
This branch has not been deployed
4 participants
Purpose
The aim is agents that spend fewer tokens, make fewer mistakes, and keep repository knowledge in the repository rather than in personal memory.
This PR puts the team's Claude Code skills in the repository so that every contributor's agent follows the same workflows.
It versions .claude/skills/:
Skills named local-* stay personal and gitignored, and the rest of .claude/ stays ignored too.
AGENTS.md gains three sections: working efficiently (focused reads, narrow tests and lint), reporting incidental findings without fixing them, and recording verified knowledge in the right place.
Auto resilient / improvement
Problems: when an agent comes across a real bug, a security issue or a clear improvement unrelated to its task, it will reports it at the end and offers to file a short issue with
docs-create-issueskill.Improvements: at the end of a task, the agent records any verified, reusable finding that would have saved time (a pitfall, a wrong command, a helper to prefer) in the narrowest place: AGENTS.md, a skill or a README. A human reviews that edit like any other code.
Along with the "Working efficiently" rules (grep before reading, no generated files, narrow checks first), this keeps agents cheaper and more reliable over time.