CLAUDE.md git:20261018.f9d7717A

Immutable. This exact content never changes and is served at /api/v1/blob/14dd68af5fe3213e.

# Repository Instructions

## Language

- Respond in Chinese unless the user requests another language.
- Use English for code, file names, commands, and commit messages.

## Git Delivery Authorization

- An explicit `commit-push` invocation authorizes committing the selected change set and pushing the current branch to its configured upstream, including `main` or `master`; do not ask for a second protected-branch confirmation.
- Before committing, inspect the branch, upstream, staged diff, and verification. Never force-push. Stop for secrets, unrelated staged changes, a missing or unexpected push target, or a failed push.

## Repository Model

- `skills/<slug>/` contains public skills indexed by the web app; `.agents/skills/` contains internal tooling and is not published.
- `.claude/skills` is a symlink to `.agents/skills` for local runtime testing.
- `skills/desktop-agent-activity`, `skills/installed-app-feature-inventory`, and `skills/dev-environment-roi-audit` are exported from a private source (listed in `.export-manifest.json`). Treat them as generated: edit the private source, not these copies; the next export overwrites local edits.
- `apps/web/src/generated/skills-index-lite.json` and `apps/web/src/generated/skills-detail-index.json` are generated web build inputs. After changing public skills, run `pnpm skills:validate` and `pnpm skills:index`; never edit the index manually.
- Every public skill needs an entry in `apps/web/content/skill-catalog.yaml` (Visitor-facing tags, summary, and use cases in English and Chinese); `pnpm skills:validate` fails without it. Keep this copy out of SKILL.md frontmatter: the Agent Skills spec allows only string `metadata` values.

## Install Targets

| Host                                    | Command                                                                                                                                              |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Codex, Cursor, other `skills` CLI hosts | `npx skills add adonis0123/adonis-skills --skill <name>` (`-g` global, `--list` to list)                                                             |
| Claude Code                             | `/plugin marketplace add Adonis0123/adonis-skills`, then `/plugin install adonis-skills@adonis-skills` (manifest: `.claude-plugin/marketplace.json`) |
| Hermes Agent                            | `hermes skills tap add adonis0123/adonis-skills`                                                                                                     |

## Commands

```bash
pnpm skills:new
pnpm skills:init <skill-name> --path skills
pnpm skills:quick-validate skills/<skill-slug>
pnpm skills:openai-yaml skills/<skill-slug>
pnpm skills:validate
pnpm skills:index
pnpm skills:install:local [-- --all | --skill <name>]
pnpm skills:test:local [-- --all | --skill <name>]
pnpm dev
pnpm lint
pnpm typecheck
pnpm build
```

- Use `pnpm skills:new` for the normal create, validate, and index flow.
- Add OpenAI metadata only when needed, using `pnpm skills:openai-yaml`.
- For app/runtime changes, run the relevant lint, typecheck, and build checks.

## Repository Conventions

- Keep changes minimal and match existing script and file naming.
- Prefer deterministic scripts over repeated manual steps.
- Change generated artifacts through their source script, then regenerate them.
- Pass script arguments explicitly through `--` in docs and CI when pnpm parsing would be ambiguous.

## Documentation Conventions

- A documented directory must contain canonical English `README.md` and matching Chinese `README.zh-CN.md`.
- Keep both files structurally and semantically aligned, including commands, and add reciprocal language links.
- Every README change must update both files in the same change.

## Skill Authoring

- Use lowercase hyphen-case for skill directories and frontmatter `name`.
- Every `skills/<slug>/SKILL.md` requires non-empty `name` and `description`; CI validates these two fields.
- Add `scripts/`, `references/`, `assets/`, or other documentation only when operationally needed.
- Add `agents/openai.yaml` only for downstream OpenAI metadata integration and generate it with `pnpm skills:openai-yaml`.
- Public skills live in `skills/`; internal skills live in `.agents/skills/` and are not indexed.

```yaml
---
name: skill-name
description: "When and why to use this skill"
allowed-tools: Read, Bash # optional
metadata: # optional
  author: your-name
  version: "1.0.0"
---
```

## Web Coding (`apps/web/**`)

- Use TypeScript and function components; follow existing imports, naming, and nearby test placement.
- Document non-obvious tradeoffs in PR descriptions.
- Prefer ahooks `useLocalStorageState` over direct `window.localStorage`. If direct access is required, document why in code.

## Plan Mode Major Changes

- This section applies only in Plan mode.
- A change is major when it crosses modules/directories, changes public interfaces/architecture/core data flow, or is expected to touch at least 5 files.
- Create one `docs/plan-YYYY-MM-DD-topic.md` per major change; use lowercase kebab-case matching `^plan-[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+\.md$`.
- Include background, goals, scope, solution, risks, and acceptance criteria.

## Web UI Contract (`apps/web/src/**` only)

- Before changing web visuals, read the root `DESIGN.md` (what the site looks like) and `docs/web-ui-clay-contract.md` (how this repo implements it); both are mandatory. `DESIGN.md` is generated by `pnpm brand:sync` from the private `adonis-brand` repo: never edit it here.
- Colors come from the private `adonis-brand` repo (`data/palette.json`, `projects/skills/theme.json`). `apps/web/src/styles/brand-tokens.css` and `theme-roles.css` are generated: change the brand repo, then run `pnpm brand:sync`; CI runs `pnpm brand:check`.
- Do not apply its visual rules to scripts, skills, or non-web packages.
- In particular, never add bottom outer highlight lines such as `0 1px 0 ...` to raised or floating shadows.