diff --git a/.gitignore b/.gitignore
index 1c15d8b..d4ea6af 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,4 +11,7 @@
 /update
 
 # Skills
-.trae
\ No newline at end of file
+.trae
+
+# Codex
+.codex
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..288d496
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,99 @@
+# Repository Guidelines
+
+## Project Shape
+
+This repository is a third-party 1Panel local app store. It is mostly YAML,
+Docker Compose files, READMEs, icons, and helper shell scripts. There is no
+central application build step.
+
+Top-level files:
+
+- `data.yaml`: app store metadata and category/tag definitions.
+- `apps/<app-key>/`: one app package per directory.
+- `skills/`: app-generation guidance, templates, and helper scripts.
+- `update/`: update-detection and README-version sync scripts.
+
+## App Package Layout
+
+Use this structure for each app:
+
+```text
+apps/<app-key>/
+├── data.yml
+├── logo.png
+├── README.md
+├── README_en.md
+└── <version>/
+    ├── data.yml
+    ├── docker-compose.yml
+    └── data/
+```
+
+Some apps also include `latest/`. When both `latest/` and a concrete version
+exist, `latest/` should use an image tagged `latest`, and the concrete version
+directory should use the pinned image tag.
+
+## 1Panel Conventions
+
+- App keys are lowercase and hyphenated, and must match the app directory name.
+- Top-level `apps/<app-key>/data.yml` contains display metadata.
+- Version-level `data.yml` contains `additionalProperties.formFields`.
+- Prefer standard port variables such as `PANEL_APP_PORT_HTTP`,
+  `PANEL_APP_PORT_HTTPS`, `PANEL_APP_PORT_API`, `PANEL_APP_PORT_ADMIN`,
+  `PANEL_APP_PORT_PROXY`, `PANEL_APP_PORT_DB`, `PANEL_APP_PORT_SSH`,
+  `PANEL_APP_PORT_S3`, and `PANEL_APP_PORT_SYNC`.
+- Each `PANEL_APP_PORT_*` used in `docker-compose.yml` should have a matching
+  form field in the version `data.yml`.
+- Compose services should use `container_name: ${CONTAINER_NAME}`,
+  `restart: always`, the external `1panel-network`, relative `./data/` volume
+  paths for persistence, and `labels: createdBy: "Apps"`.
+- Use `./data/...` mounts instead of host absolute paths unless the app
+  genuinely requires host integration.
+- Keep app metadata tags aligned with `data.yaml`.
+
+## App Creation Workflow
+
+Before adding or changing app packages, read `skills/SKILL.md`. It documents
+the expected 1Panel packaging workflow, metadata fields, compose conversion
+rules, README shape, and icon lookup order.
+
+Useful helper scripts:
+
+```bash
+cd /root/github/1Panel-Appstore/skills
+./scripts/generate-app.sh <github-url-or-compose-or-docker-run>
+./scripts/download-icon.sh <app-name> <output-path> 200
+./scripts/validate-app.sh ../apps/<app-key>
+```
+
+The generator is a starting point. Review and adjust generated metadata,
+ports, volumes, environment variables, README content, and icons before
+considering the app complete.
+
+## Validation
+
+For a changed app, run:
+
+```bash
+cd /root/github/1Panel-Appstore
+./skills/scripts/validate-app.sh ./apps/<app-key>
+```
+
+For YAML or Compose edits, also inspect the affected files directly. The
+validator is shell/grep based and catches common structural problems, not every
+semantic issue.
+
+## Update Scripts
+
+The scripts in `update/` may perform network requests and `git pull`. Do not run
+them casually while making focused app edits. If using them, inspect the script
+and current worktree first.
+
+## Editing Notes
+
+- Preserve existing YAML indentation style within the file being edited.
+- Keep READMEs concise and app-focused; many apps include both Chinese and
+  English README files.
+- Do not replace real logos with placeholders. If an icon cannot be found, call
+  that out instead of inventing an inaccurate asset.
+- Treat unrelated changes in the worktree as user-owned and leave them alone.