Mas Skills

MAS Skills

Objective

Provide one routing entrypoint for MAS engineering standards and keep implementation decisions consistent with current project maintainer review preferences.

Repository Authority

AUTO-MAS splits responsibilities across repositories:

1. AUTO-MAS-Project/AUTO-MAS keeps application code and a minimal AGENTS.md entrypoint.
2. AUTO-MAS-Project/AUTO-MAS-docs / https://doc.auto-mas.top/developer/ owns branch, contribution, commit, version, Issue, and PR writing rules.
3. Local .agents/skills owns the project-affiliated Agent Skill behavior and engineering routing rules for this checkout.

When these areas overlap, use this skill for engineering decisions and use the docs site for contribution-process decisions.

Project Rule Areas

Apply these project rules directly when they overlap with a task:

1. Cherry-picks to an already released release/{version} branch must be small pure-backend fixes that touch no frontend code, because released apps hot-update only backend code from that branch while the frontend ships inside the installer. Cherry-picking a commit that carries frontend logic is a violation: close the related PR and revert the related commit. Judge by the files the commit actually touches, not by the type / scope in its message. Never help prepare or push such a cherry-pick.

2. API work follows the schema-first route flow: define app/models/schema.py, wire the matching app/api/ module, then regenerate frontend API clients.

3. Config work follows ConfigBase and ConfigItem ownership: declare fields before super().__init__(), use validators as auto-correction behavior, and register multi-config classes in the owning collection.

4. Script adaptation must be complete across config, schema, API, task dispatch, task folder, and frontend entry points, and must respect the black-box boundary: lower the configuration barrier before filling any gap, then decide capability ownership: work the script owns (in-game actions, task execution and verdicts, script config semantics) may only be reused through upstream entry points; when upstream lacks such work, consider contributing it upstream first and only fill in inside MAS as a temporary measure (marked for removal once upstream ships it) when that is not viable; MAS-owned domains (accounts, scheduling, plans, notifications, statistics, emulator lifecycle, cross-script orchestration) may be implemented in MAS but must not read or infer upstream internal state; upstream private formats may only be passed through, never modeled on, and no self-invented verdicts for upstream-executed tasks. Once upstream ships an entry point for such work, existing implementations become violations and must be replaced by reuse. After this skill is loaded, self-check the task and, on a hit, report "This may violate the MAS development norms" with file:line evidence and an alternative; the warning does not block work. Read .agents/skills/mas-script-specialized-adapter/references/blackbox-boundary.md before designing.

5. Frontend work follows the dedicated frontend skills in this directory.

6. Contribution style follows Conventional Commits, Google-style backend docstrings where useful, config-item comments, and keyword arguments for booleans or multi-argument calls.

7. CI must pin every external reference to immutable content: GitHub Actions uses entries use a full 40-character commit SHA with a # <tag> version comment (resolve annotated tags to the peeled commit), and container images use @sha256:<digest>. Apply this across GitHub workflows, composite actions, and CNB pipelines; local actions such as ./.github/actions/... are the only exception. Never leave a mutable tag, branch, or short hash. When changing CI, scan every uses: and image: reference and verify that all external references remain pinned.

8. Start every branch from the latest upstream dev (git fetch first; in a fork, branch off upstream dev), never from a stale local dev: a branch built on an old baseline silently overwrites other people's merged work when it is synced, with no conflict and green type checks. Branch rules: https://doc.auto-mas.top/developer/development-specifications.html.

Sub-Skills

Use these skills as needed:

1. mas-frontend-standards: Vue 3, TypeScript, Vite, Electron renderer, routing, API composables, state, styles, forms, validation, and frontend verification.
2. mas-frontend-ui: Ant Design Vue UI, desktop business layout, visual tokens, forms, tables, dialogs, feedback, drag interactions, dark mode, and UX constraints.
3. mas-code-standards: project code standards derived from representative dev commits and existing AUTO-MAS modules.
4. mas-schema-naming: canonical naming for shared schema semantics in future domain work.
5. mas-module-boundary: module ownership and dependency direction across backend layers.
6. mas-function-design: function-level design for responsibility, signatures, side effects, and errors.
7. mas-api-contract: endpoint contract standards for HTTP/WS request-response behavior.
8. mas-data-model: modeling standards for schema/config/task layers and compatibility evolution.
9. mas-script-specialized-adapter: specialized script integration by script frontend architecture line; requires intake before implementation.
10. mas-plan-schedule: plan schedule type registration, backend/frontend plan dispatch, plan combobox consumers, and per-type table integration.
11. mas-game-sign: game community sign-in providers, credential encryption and login routes, sign-in locks and trigger paths, and result/notification contracts.

Global Constraints

Apply these constraints before selecting or combining sub-skills.

1. Make minimal necessary changes first; avoid broad refactors unless explicitly requested.
2. Align with current code style and existing project conventions in the touched module.
3. Avoid over-engineering, over-abstraction, and defensive programming that does not match existing code patterns.
4. Study similar existing implementations deeply before coding and follow established local patterns.
5. Never edit files generated by OpenAPI code generation under any circumstance. If regeneration is needed, explicitly tell the developer to run the generation process manually.
6. For frontend work, load mas-frontend-standards; for UI or user-facing component behavior, also load mas-frontend-ui.
7. When local patterns and generalized guidance differ, prefer concrete maintainer review comments and fold them back into the selected sub-skills.
8. Before completing a user-visible feature or fix, add exactly one changelog fragment under changelog.d/ (<PR number or branch>.<feat|change|fix|breaking|remove|security|dev>.md; first line project: <key> from the project table in changelog.d/README.md — 14 adapters plus home / scheduler / emulator / notify / tools / settings / update / runtime, no catch-all, pick the nearest per the README; only dev fragments may omit it; then one user-facing sentence of at most 50 characters without project prefix, PR number or signature; python scripts/changelog.py add <type> <project> "<sentence>" creates it, with - as the project for dev). Before writing a fix or change fragment, decide which release introduced the feature you touch: a feature absent from the previous stable release's notes was introduced in the current X.Y.0 cycle (for 5.5.0: Runtime initialization, virtual display, Emulator 2.0, MFW, BetterGI, BAAH, ZZZ-OD, config restore, operator cultivation). Every later fix, maintenance or supplementary change to such a feature (bug fixes, turning something into a prompt, extra hints, default tweaks, layout changes, i18n wiring, cleanup) is beta-only: if the feature's entry is still in the top ## [未发布] section or its fragment is still in changelog.d/, add no fragment and label the PR skip-changelog (describe any wording change in the PR for a maintainer to apply); if it shipped in an earlier beta of the cycle, add the header line beta-only: true so the entry is dropped from the stable roll-up. Sub-features added to it later are beta-only as well: in the stable notes a new adapter is exactly one line (【bgi】新增 bgi 专项) and a new feature is its single introduction entry; fixes and changes to features that shipped in the previous stable are normal. Project keys use the short names bgi (BetterGI) and end (MaaEnd). A PR with several human authors lists them all in the header line author: a, b (the script never reads Co-authored-by). Maintainers may add highlight: true to route an entry into 「本次亮点」 as part of the implementation; do not merely remind the developer. Condense all changes of the PR into that one sentence. Never edit CHANGELOG.md, res/version.json or any version number: they are written only by the release PR. Do not create a commit unless the user explicitly asks for one.