Add .agents/skills AI agent system #2767
Conversation
Reviewer's GuideIntroduces an AI-focused skills and context system under File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
ArnavBallinCode
changed the title
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The links to
DEPLOYMENT.mdin.github/instructions/DOCKERFILE.instructions.mdand.agents/skills/docker-deployment.mdare relative to their own directories and will currently 404; adjust them to the correct relative path (e.g.../../DEPLOYMENT.md). - The Docker environment variable guidance in
.github/instructions/DOCKERFILE.instructions.md(usingPOSTGRES_*) and.agents/skills/docker-deployment.md(mentioningDATABASE_URLorPOSTGRES_*) is slightly inconsistent; consider standardizing the recommended pattern in both documents to avoid confusion.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The links to `DEPLOYMENT.md` in `.github/instructions/DOCKERFILE.instructions.md` and `.agents/skills/docker-deployment.md` are relative to their own directories and will currently 404; adjust them to the correct relative path (e.g. `../../DEPLOYMENT.md`).
- The Docker environment variable guidance in `.github/instructions/DOCKERFILE.instructions.md` (using `POSTGRES_*`) and `.agents/skills/docker-deployment.md` (mentioning `DATABASE_URL` or `POSTGRES_*`) is slightly inconsistent; consider standardizing the recommended pattern in both documents to avoid confusion.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
There was a problem hiding this comment.
Pull request overview
Adds an AI-agent guidance system under .agents/skills/ and introduces Docker/Compose-specific instruction documentation, with a small README update to point contributors/agents to the new guidance.
Changes:
- Add
.agents/README.mdplus a set of.agents/skills/*.md“skill” documents describing repo layout and development conventions. - Add
.github/instructions/DOCKERFILE.instructions.mdto document Docker/Compose workflows and configuration. - Update
README.rstwith an “AI Development” section linking to the new guidance.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| README.rst | Adds a short section pointing to AI guidance directories/files. |
| .github/instructions/DOCKERFILE.instructions.md | New Docker/Compose reference intended to act as scoped instructions. |
| .agents/README.md | New index/read-order doc for agent guidance and skills. |
| .agents/skills/repo-navigation.md | Documents current repo structure and key locations. |
| .agents/skills/django-backend.md | Summarizes backend layout and conventions for agents. |
| .agents/skills/python-style.md | Summarizes Python style expectations and runtime baseline. |
| .agents/skills/javascript-style.md | Summarizes JS/Vue expectations and file locations. |
| .agents/skills/docker-deployment.md | Summarizes Compose usage and deployment basics. |
| .agents/skills/git-workflow.md | Summarizes commit/PR workflow guidance. |
| .agents/skills/documentation.md | Summarizes where/how to update docs in the repo. |
|
Avoid naming files with uppercase. Uppercase is to get attention from human, whereas these files are for machine (AI agents). Things like coding convention, coding style, code quality should be in GitHub instructions. |
yes, will update , need to improvise a bit more.
Some tools like Antigravity don't have specific files they read , such new tools which are not tuned by the users themselves read the README.md before so I had updated that to include it too.. |
There was a problem hiding this comment.
Pull request overview
Adds a structured “AI agent skills” documentation system to help AI tooling navigate the repo and follow project conventions, and introduces Docker/Compose guidance as a file-scoped instruction.
Changes:
- Adds
.agents/README.mdand multiple.agents/skills/*.mddocuments describing repo layout and key engineering conventions. - Adds
.github/instructions/DOCKERFILE.instructions.mdto document Docker Compose stacks, services, env vars, and workflows for Docker-related file edits. - Updates
README.rstto point AI tools at.github/instructions/and the new.agents/guidance.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.rst | Adds an “AI Development” section linking to instruction/skills docs. |
| .github/instructions/DOCKERFILE.instructions.md | New Docker/Compose reference to guide edits to Dockerfiles/compose files. |
| .agents/README.md | Reading-order index for agent policy + skill documents. |
| .agents/skills/repo-navigation.md | Documents top-level and app/ layout and key “where do I put X?” pointers. |
| .agents/skills/django-backend.md | Summarizes Django backend structure, workflows, and conventions. |
| .agents/skills/python-style.md | Summarizes Python conventions and points to canonical scoped instructions. |
| .agents/skills/javascript-style.md | Summarizes JS/Vue conventions and points to canonical scoped instructions. |
| .agents/skills/git-workflow.md | Summarizes commit/PR workflow and points to canonical commit instructions. |
| .agents/skills/documentation.md | Summarizes documentation locations and update expectations. |
| .agents/skills/docker-deployment.md | Summarizes Docker dev/prod stacks and workflows for agents. |
There was a problem hiding this comment.
Pull request overview
Adds an “AI agent skills” documentation system to capture repo-specific operational knowledge for AI tooling, plus a new Docker/Compose reference instruction, and links it from the main README.
Changes:
- Add
.agents/README.mdand a set of.agents/skills/*.mdfiles documenting repo navigation, backend structure, style, Docker workflows, git workflow, and documentation practices. - Add
.github/instructions/DOCKERFILE.instructions.mdto document Docker/Compose conventions and workflows for container-related files. - Add an “AI Development” section to
README.rstpointing to the new AI guidance locations.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| README.rst | Adds an “AI Development” section linking to AI guidance locations. |
| .github/instructions/DOCKERFILE.instructions.md | Introduces a Docker/Compose reference instruction document for Docker-related files. |
| .agents/README.md | Adds an AI-agent reading order and skills index. |
| .agents/skills/repo-navigation.md | Documents repository layout and where to find key components. |
| .agents/skills/django-backend.md | Documents Django backend layout, conventions, and local workflows. |
| .agents/skills/python-style.md | Summarizes Python conventions (defers to canonical instructions). |
| .agents/skills/javascript-style.md | Summarizes JS conventions (defers to canonical instructions). |
| .agents/skills/git-workflow.md | Summarizes git/commit and PR expectations (defers to canonical instructions). |
| .agents/skills/documentation.md | Summarizes documentation locations and update guidance. |
| .agents/skills/docker-deployment.md | Summarizes Docker/Compose dev vs prod workflows and key files. |
|
The .agents/skills/xxx-style.md files are duplicate with the ones in GH instructions. Follow this spec for how the files under .agents/skills/ should be: https://agentskills.io/what-are-skills |
ArnavBallinCode
force-pushed
the
copilot-agents-skills
branch
from
5a4e54a to
9a3911c
Compare
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- The Docker-related env var names are inconsistent between
.github/instructions/dockerfile.instructions.md(e.g.EVY_SECRET_KEY,EVY_POSTGRES_*,EVY_REDIS_URL) and.agents/skills/docker-deployment/skill.md(e.g.DJANGO_SECRET_KEY,DATABASE_URL,REDIS_URL,SERVER_NAME); please align these with the actualdeployment/env*.samplefiles so agents don’t get conflicting guidance. - Given the new note in
agents.mdthat skills should summarize and reference existing instructions, consider trimming duplicated Docker/deployment details from.agents/skills/docker-deployment/skill.mdand instead explicitly point to.github/instructions/dockerfile.instructions.md/DEPLOYMENT.mdto reduce drift between files.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The Docker-related env var names are inconsistent between `.github/instructions/dockerfile.instructions.md` (e.g. `EVY_SECRET_KEY`, `EVY_POSTGRES_*`, `EVY_REDIS_URL`) and `.agents/skills/docker-deployment/skill.md` (e.g. `DJANGO_SECRET_KEY`, `DATABASE_URL`, `REDIS_URL`, `SERVER_NAME`); please align these with the actual `deployment/env*.sample` files so agents don’t get conflicting guidance.
- Given the new note in `agents.md` that skills should summarize and reference existing instructions, consider trimming duplicated Docker/deployment details from `.agents/skills/docker-deployment/skill.md` and instead explicitly point to `.github/instructions/dockerfile.instructions.md` / `DEPLOYMENT.md` to reduce drift between files.
## Individual Comments
### Comment 1
<location path=".github/instructions/dockerfile.instructions.md" line_range="117" />
<code_context>
+docker compose -f deployment/docker-compose.yml up -d
+```
+
+Refer to [`DEPLOYMENT.md`](../../DEPLOYMENT.md) for the complete step-by-step guide including SSL setup with certbot.
+
+---
</code_context>
<issue_to_address>
**issue (typo):** Capitalize the product name “Certbot”
Please capitalize the product name here: “including SSL setup with Certbot.”
```suggestion
Refer to [`DEPLOYMENT.md`](../../DEPLOYMENT.md) for the complete step-by-step guide including SSL setup with Certbot.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
|
@hongquan what do you think about the new structure ? Do you think we should add |
There was a problem hiding this comment.
Pull request overview
Adds a structured “AI agent skills” knowledge base under .agents/skills/ and expands repository guidance by documenting where to find frontend code, Docker/Compose workflows, and AI-related reading order.
Changes:
- Introduce
.agents/skills/*skill documents for repo navigation, Django backend, Docker deployment, and documentation updates. - Add a new Docker/Compose reference under
.github/instructions/dockerfile.instructions.md. - Update
agents.md,README.rst, and existing instruction docs to reference the new guidance.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
agents.md |
Adds .agents/skills/ to the agent-policy hierarchy and a skills index. |
README.rst |
Adds an “AI Development” section pointing readers to instructions and skills. |
.github/instructions/js.instructions.md |
Documents where frontend code lives and notes Vue 3 usage. |
.github/instructions/git-commit.instructions.md |
Adds branching and PR expectations to commit guidance. |
.github/instructions/dockerfile.instructions.md |
New Docker/Compose reference for dev + production workflows. |
.agents/skills/repo-navigation/skill.md |
Documents repo layout and “where to find things.” |
.agents/skills/documentation/skill.md |
Documents key documentation files and update practices. |
.agents/skills/docker-deployment/skill.md |
Summarizes Compose stacks, services, and workflows. |
.agents/skills/django-backend/skill.md |
Summarizes Django project structure and backend conventions. |
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- The new architecture context and repo-navigation skill both describe the backend layout but with slightly different emphases (e.g.,
eventyay_common/,webapp/, template locations); consider consolidating or cross-linking these so they can’t drift out of sync over time. - The expanded JS instructions now cover legacy JS and modern Vue 3 (
app/**/*.{js,ts,vue}) in a single file; it might be clearer to split guidance or sections explicitly by stack (legacy static JS vs bundled Vue apps) so agents can easily apply the right conventions and build workflows.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new architecture context and repo-navigation skill both describe the backend layout but with slightly different emphases (e.g., `eventyay_common/`, `webapp/`, template locations); consider consolidating or cross-linking these so they can’t drift out of sync over time.
- The expanded JS instructions now cover legacy JS and modern Vue 3 (`app/**/*.{js,ts,vue}`) in a single file; it might be clearer to split guidance or sections explicitly by stack (legacy static JS vs bundled Vue apps) so agents can easily apply the right conventions and build workflows.
## Individual Comments
### Comment 1
<location path=".agents/skills/django-run-locally/skill.md" line_range="16" />
<code_context>
+2. Synchronously install or update environment dependencies strictly through `uv`: `uv sync --all-extras --all-groups`
+3. Activate the standard CLI venv wrapper: `. .venv/bin/activate`
+4. Deploy local DB schema synchronization calls: `python manage.py migrate`
+5. *(Optional)* Setup initial admin: `python manage.py create_admin_user`
+6. Build Frontend Assets:
+ ```bash
</code_context>
<issue_to_address>
**nitpick (typo):** Use the verb form "set up" instead of the noun "setup" here.
```suggestion
5. *(Optional)* Set up initial admin: `python manage.py create_admin_user`
```
</issue_to_address>
### Comment 2
<location path=".agents/skills/django-run-locally/skill.md" line_range="34" />
<code_context>
+## Gotchas
+
+- **Strict Environment Imports**: If context dynamically requires variable settings locally, ALWAYS safely fetch these utilizing `from django.conf import settings`. Never import the isolated system settings configuration natively (e.g. absolutely never execute `from eventyay.config import settings`).
+- **CSS not loading / MIME type errors**: Ensure you have successfully run `collectstatic` and `compress --force` steps to properly build the Javascript/CSS chunks.
</code_context>
<issue_to_address>
**issue (typo):** Capitalize "JavaScript" correctly in "Javascript/CSS".
Please update this instance to the correct capitalization, "JavaScript", to match standard usage and remain consistent with the rest of the documentation.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| 2. Synchronously install or update environment dependencies strictly through `uv`: `uv sync --all-extras --all-groups` | ||
| 3. Activate the standard CLI venv wrapper: `. .venv/bin/activate` | ||
| 4. Deploy local DB schema synchronization calls: `python manage.py migrate` | ||
| 5. *(Optional)* Setup initial admin: `python manage.py create_admin_user` |
There was a problem hiding this comment.
nitpick (typo): Use the verb form "set up" instead of the noun "setup" here.
| 5. *(Optional)* Setup initial admin: `python manage.py create_admin_user` | |
| 5. *(Optional)* Set up initial admin: `python manage.py create_admin_user` |
| ## Gotchas | ||
|
|
||
| - **Strict Environment Imports**: If context dynamically requires variable settings locally, ALWAYS safely fetch these utilizing `from django.conf import settings`. Never import the isolated system settings configuration natively (e.g. absolutely never execute `from eventyay.config import settings`). | ||
| - **CSS not loading / MIME type errors**: Ensure you have successfully run `collectstatic` and `compress --force` steps to properly build the Javascript/CSS chunks. |
There was a problem hiding this comment.
issue (typo): Capitalize "JavaScript" correctly in "Javascript/CSS".
Please update this instance to the correct capitalization, "JavaScript", to match standard usage and remain consistent with the rest of the documentation.
There was a problem hiding this comment.
Pull request overview
Adds a structured “AI agent skills” knowledge base under .agents/skills/ and expands the repository’s AI/contributor guidance so agents have clearer, file-scoped instructions and repo navigation/deployment context.
Changes:
- Introduce
.agents/skills/and.agents/context/with skill/context markdown files for repo navigation, Django workflows, Docker deployment, and documentation updates. - Extend
agents.mdandREADME.rstto reference the new skills/context system and clarify reading/precedence. - Broaden existing instruction files (JS/Vue scope, git commit expectations) and add a new Dockerfile/Compose instruction document.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
agents.md |
Adds skills/context indexes and updates instruction precedence. |
README.rst |
Adds an “AI Development” section pointing to instructions and skills. |
.github/instructions/js.instructions.md |
Expands scope to TS/Vue and documents frontend code locations + Vue 3 guidance. |
.github/instructions/git-commit.instructions.md |
Adds branching/PR expectation guidance on top of commit message rules. |
.github/instructions/dockerfile.instructions.md |
New Docker/Compose reference and workflows for dev/prod. |
.agents/skills/repo-navigation/skill.md |
Documents repo layout and where key code areas live. |
.agents/skills/documentation/skill.md |
Documents where/how to update repository documentation. |
.agents/skills/docker-deployment/skill.md |
Summarizes Compose stacks, services, and common container commands. |
.agents/skills/django-run-migrations/skill.md |
Describes makemigrations/migrate workflow and validation/gotchas. |
.agents/skills/django-run-locally/skill.md |
Documents non-Docker local dev steps (uv/venv/static build/runserver). |
.agents/skills/django-create-model/skill.md |
High-level steps for adding/updating Django models in the correct sub-app. |
.agents/skills/django-create-api-endpoint/skill.md |
High-level steps for adding DRF serializers/viewsets/routes. |
.agents/skills/django-add-management-command/skill.md |
High-level steps for adding Django management commands. |
.agents/skills/django-add-form/skill.md |
High-level steps for adding/validating Django forms in domain sub-apps. |
.agents/context/architecture.md |
Adds architectural context for the Django backend layout and settings model. |
There was a problem hiding this comment.
Pull request overview
Introduces a structured “AI agent” knowledge system for the repository by adding .agents/context and .agents/skills, and expands contributor/agent guidance across documentation, frontend conventions, git workflow, and Docker usage.
Changes:
- Adds
.agents/context/and.agents/skills/files to document repo architecture and common workflows (Django, Docker, docs). - Updates
agents.mdandREADME.rstto reference the new AI guidance structure and recommended reading order. - Extends
.github/instructions/guidance for JS/Vue scope, git expectations, and adds Docker/Docker Compose reference instructions.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
agents.md |
Declares policy precedence and indexes new context/skills docs. |
README.rst |
Adds an “AI Development” section pointing to instructions and agents.md. |
.github/instructions/js.instructions.md |
Expands guidance scope to include TS/Vue and documents frontend locations. |
.github/instructions/git-commit.instructions.md |
Adds branching and PR expectations guidance. |
.github/instructions/dockerfile.instructions.md |
Adds Docker/Docker Compose operational reference and workflows. |
.agents/skills/repo-navigation/skill.md |
Documents repo layout and where key code/docs live. |
.agents/skills/documentation/skill.md |
Documents where/how to update project documentation. |
.agents/skills/docker-deployment/skill.md |
Summarizes Docker dev/prod stacks and common commands. |
.agents/skills/django-run-migrations/skill.md |
Summarizes migration workflow and gotchas. |
.agents/skills/django-run-locally/skill.md |
Documents running Django locally without Docker. |
.agents/skills/django-create-model/skill.md |
Summarizes workflow for adding/modifying Django models. |
.agents/skills/django-create-api-endpoint/skill.md |
Summarizes workflow for adding DRF endpoints. |
.agents/skills/django-add-form/skill.md |
Summarizes workflow for adding/updating Django forms. |
.agents/context/architecture.md |
Captures high-level backend architecture and settings conventions. |
| - **Production (`deployment/docker-compose.yml`)**: Uses a pre-built image (`eventyay/eventyay-next:${TAG}`) rather than building it locally. This image is built from `app/Dockerfile.prod` via CI/CD pipelines. Static assets are pre-built and served directly via the Nginx reverse-proxy fronting the Gunicorn application server. | ||
|
|
||
| For the full production deployment walkthrough including Nginx, SSL, and backups, see [`DEPLOYMENT.md`](../../DEPLOYMENT.md). | ||
|
|
||
| ## Files | ||
|
|
||
| | File | Purpose | | ||
| |---|---| | ||
| | `docker-compose.yml` | Development / local stack | | ||
| | `deployment/docker-compose.yml` | Production stack | | ||
| | `deployment/env.dev.sample` | Sample development environment variables | |
|
@ArnavBallinCode Sorry, the lowercase filename "skill.md" is not recognized by AI agents. Please change them to uppercase. |
|
@ArnavBallinCode For context/architecture.md, I don't see any spec about it. Where should it be placed? We can try to put it under ".agents/". |
I think separating instructions, skills, and context is better. Since architecture.md is descriptive (not executable like skills or rules like instructions), we keep it under .agents/context/ so the agent can retrieve it when needed without bloating skills. We can extend this with other context files like api-patterns.md, data-modeling.md, etc. |
Agree. |
There was a problem hiding this comment.
Pull request overview
Adds an “AI agent system” layer to the repo by introducing .agents/context/ and .agents/skills/ documentation, and updates existing contributor/agent guidance to reference and apply these resources.
Changes:
- Document AI policy precedence and add indexes for available agent context + skills (
agents.md,README.rst). - Expand file-scoped instruction coverage for modern frontend files (TS/Vue) and add frontend location notes (
.github/instructions/js.instructions.md). - Add Docker/container workflow reference and add initial set of skill/context documents under
.agents/.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| README.rst | Adds an “AI Development” section pointing to .github/instructions/ and .agents/skills/. |
| agents.md | Updates precedence rules and adds context/skills index tables. |
| .github/instructions/js.instructions.md | Expands applyTo to js/ts/vue and documents frontend code locations + Vue 3 note. |
| .github/instructions/git-commit.instructions.md | Adds branching and PR expectations guidance. |
| .github/instructions/dockerfile.instructions.md | New Docker/Docker Compose reference for dev/prod workflows and env vars. |
| .agents/context/architecture.md | New architecture/context overview for backend structure and settings configuration. |
| .agents/skills/repo-navigation/SKILL.md | New repo navigation skill documenting key directories and lookup shortcuts. |
| .agents/skills/documentation/SKILL.md | New documentation-update skill. |
| .agents/skills/docker-deployment/SKILL.md | New docker deployment skill summarizing key compose files, services, and commands. |
| .agents/skills/django-run-migrations/SKILL.md | New migration workflow skill. |
| .agents/skills/django-run-locally/SKILL.md | New local (non-Docker) dev run skill. |
| .agents/skills/django-create-model/SKILL.md | New model creation/modification skill. |
| .agents/skills/django-create-api-endpoint/SKILL.md | New API endpoint creation skill. |
| .agents/skills/django-add-form/SKILL.md | New Django form creation/validation skill. |
| | `.agents/skills/repo-navigation/skill.md` | Repository layout and where to find code | | ||
| | `.agents/skills/django-create-model/skill.md` | Steps for creating or modifying a Django model | | ||
| | `.agents/skills/django-create-api-endpoint/skill.md` | Steps for adding a new Django REST Framework API endpoint | | ||
| | `.agents/skills/django-add-form/skill.md` | Steps for creating or modifying Django forms and adding validation | | ||
| | `.agents/skills/django-run-migrations/skill.md` | Steps for generating and applying Django migrations | | ||
| | `.agents/skills/django-run-locally/skill.md` | Steps for initiating the Django development server without Docker | | ||
| | `.agents/skills/docker-deployment/skill.md` | Docker Compose, container services, deployment | | ||
| | `.agents/skills/documentation/skill.md` | How to update project documentation | |
There was a problem hiding this comment.
The Skills Index points to .agents/skills/.../skill.md, but the skill files added in this PR are named SKILL.md (uppercase). As written, these links/paths won’t resolve for agents or contributors. Update the index to match the actual filenames (or rename the files to skill.md) consistently across all entries.
| | `.agents/skills/repo-navigation/skill.md` | Repository layout and where to find code | | |
| | `.agents/skills/django-create-model/skill.md` | Steps for creating or modifying a Django model | | |
| | `.agents/skills/django-create-api-endpoint/skill.md` | Steps for adding a new Django REST Framework API endpoint | | |
| | `.agents/skills/django-add-form/skill.md` | Steps for creating or modifying Django forms and adding validation | | |
| | `.agents/skills/django-run-migrations/skill.md` | Steps for generating and applying Django migrations | | |
| | `.agents/skills/django-run-locally/skill.md` | Steps for initiating the Django development server without Docker | | |
| | `.agents/skills/docker-deployment/skill.md` | Docker Compose, container services, deployment | | |
| | `.agents/skills/documentation/skill.md` | How to update project documentation | | |
| | `.agents/skills/repo-navigation/SKILL.md` | Repository layout and where to find code | | |
| | `.agents/skills/django-create-model/SKILL.md` | Steps for creating or modifying a Django model | | |
| | `.agents/skills/django-create-api-endpoint/SKILL.md` | Steps for adding a new Django REST Framework API endpoint | | |
| | `.agents/skills/django-add-form/SKILL.md` | Steps for creating or modifying Django forms and adding validation | | |
| | `.agents/skills/django-run-migrations/SKILL.md` | Steps for generating and applying Django migrations | | |
| | `.agents/skills/django-run-locally/SKILL.md` | Steps for initiating the Django development server without Docker | | |
| | `.agents/skills/docker-deployment/SKILL.md` | Docker Compose, container services, deployment | | |
| | `.agents/skills/documentation/SKILL.md` | How to update project documentation | |
| ```bash | ||
| # On the production server | ||
| cd /home/$USER/$DEPLOYMENT_NAME | ||
| docker compose -f docker-compose.yml up -d |
There was a problem hiding this comment.
The production compose file in this repo is deployment/docker-compose.yml, but the example uses docker compose -f docker-compose.yml up -d without explaining that the file needs to be copied/symlinked into the current directory first. Consider either using the explicit path (-f deployment/docker-compose.yml) or documenting the expected copy/symlink step to avoid broken commands.
| docker compose -f docker-compose.yml up -d | |
| # Use the production compose file from the deployment/ directory | |
| docker compose -f deployment/docker-compose.yml up -d |
| **Core Architecture Principle:** | ||
| - **Development (`docker-compose.yml`)**: Builds directly from `app/Dockerfile`. The `web` container serves static assets directly via Django. | ||
| - **Production (`deployment/docker-compose.yml`)**: Uses a pre-built image (`eventyay/eventyay-next:${TAG}`) rather than building it locally. This image is built from `app/Dockerfile.prod` via CI/CD pipelines. Static assets are pre-built and served directly via the Nginx reverse-proxy fronting the Gunicorn application server. | ||
|
|
There was a problem hiding this comment.
This document describes production as being served via an Nginx reverse proxy, but deployment/docker-compose.yml does not define an nginx service (Nginx is set up on the host per DEPLOYMENT.md). To avoid confusion, clarify that the reverse proxy is host-level (or add an explicit note that it’s not part of the compose stack).
| ## Directory Map (`app/eventyay/`) | ||
|
|
||
| ```text | ||
| app/ | ||
| ├── eventyay/ # Main unifying package | ||
| │ ├── config/ # System configuration and settings.py files | ||
| │ ├── api/ # DRF viewsets, serializers, routers | ||
| │ ├── base/ # Core shared models, managers, forms, and middleware | ||
| │ ├── control/ # Organiser back-office (management UI, forms, urls) | ||
| │ ├── presale/ # Attendee-facing (ticket purchase, public pages, urls) | ||
| │ ├── eventyay_common/ # Modern shared UI components and base templates | ||
| │ ├── webapp/ # Modern Vue 3 bundled front-end applications | ||
| │ ├── static/ # Legacy/Django-served static assets (CSS, images) | ||
| │ ├── celery.py # Celery task application configuration | ||
| │ └── plugins/ # Extendible plugin architecture definitions | ||
| ├── tests/ # Pytest testing suite | ||
| └── manage.py |
There was a problem hiding this comment.
The directory map for app/eventyay/ omits several top-level packages that exist in the repo (e.g. orga/, agenda/, cfp/, etc.). Since this section is labeled as a “Directory Map”, either include the missing major directories or rename/qualify the section as a non-exhaustive/selected subset to prevent readers from assuming these modules don’t exist.
| | Directory | Purpose | | ||
| |---|---| | ||
| | `api/` | REST API endpoints (Django REST Framework) | | ||
| | `base/` | Shared models (`base/models/`), utilities, middleware, and forms (`base/forms/`) | | ||
| | `control/` | Organiser/back-office views, forms, and URLs | | ||
| | `presale/` | Attendee-facing (ticket purchase) views and forms | | ||
| | `common/` | Cross-cutting helpers shared across modules | | ||
| | `config/` | Application configuration and settings | | ||
| | `plugins/` | Plugin infrastructure | | ||
| | `static/` | Static assets (CSS, JS, images) | |
There was a problem hiding this comment.
The app/eventyay/ “Core Application” table doesn’t mention orga/, which exists and is a major module in this repo. For a “where to find code” skill, either add orga/ (and any other key modules you expect agents to touch) or clarify that the table is intentionally non-exhaustive.
|
|
||
| ```bash | ||
| docker compose exec web python manage.py migrate | ||
| docker compose exec web python manage.py createsuperuser |
There was a problem hiding this comment.
For this repo, python manage.py create_admin_user is the documented way to create an initial admin without granting full superuser privileges (see app/eventyay/base/management/commands/create_admin_user.py). Using createsuperuser here may encourage over-privileged accounts. Consider switching the example to create_admin_user (and optionally mentioning createsuperuser as an advanced alternative).
| docker compose exec web python manage.py createsuperuser | |
| docker compose exec web python manage.py create_admin_user |
Also partial part of #2737
!! Needs clarification of Deployment and Docker instructions.
Future Plan
We plan to further align with the Agent Skills specification and improve the quality, modularity, and execution capability of our skills.
1. Standardize Skill Structure
Move towards a richer, extensible structure:
2. Improve Skill Quality
3. Introduce Progressive Disclosure
SKILL.mdminimal (core logic only)references/4. Add Execution Support via Scripts
scripts/This avoids the agent re-deriving logic each time.
5. Expand Context Layer
Extend
.agents/context/beyondarchitecture.md:This improves retrieval and reduces hallucination.
6. Introduce Skill Composition
7. Continuous Refinement Loop
Summary by Sourcery
Introduce an AI agent skills and context system and expand contributor guidance for JavaScript/Vue, Docker, and git workflows.
New Features:
.agents/skills/and a context index under.agents/context/for repository navigation, Django workflows, Docker deployment, and documentation updates.Enhancements:
agents.mdas the single source of truth and documenting the new skills and context directories.