# concept-skills

Concept design, semantic modeling, knowledge organization and visual teaching.

## Repository ownership

| Repository | Owns |
| --- | --- |
| `concept-skills` | Software concepts, semantic modeling, knowledge organization, and visual learning. |
| `cloud-concept-skills` | Huawei Cloud operations, billing, controlled provisioning, and account onboarding. |
| `myoffice-skills` | Office workflows, presentations, source notes, repository guidance, and Agent DX tooling. |

## Directory contract

| Directory | Contract |
| --- | --- |
| `skills/en/<name>/`, `skills/cn/<name>-cn/` | Self-contained install payloads, including required `references/`, assets and runtime scripts. |
| `qa/<locale>/<name>/` | Validation, fixtures, eval definitions, per-skill `VERSION` and current changelog. |
| `catalog.yml` | Tracked discovery metadata used by QA and publishing tools. |
| `docs/` | Concise local notes and examples; ignored by Git and never required by QA or distribution. |
| `tools/`, `.githooks/`, `.github/` | Repository tooling, local commit/push gates and CI. |
| `template/` | Maintained scaffolding for new skills and QA. |

Learning copies, downloaded repositories, process notes, raw outputs and generated eval workspaces
belong outside the checkout, normally in a task-specific temporary directory. Delete them when no
longer needed. Preserve runtime `skills/**/references/` and maintained fixtures/examples.

## Change and release rules

- Update the owning repository; keep sibling projects independent and link rather than copy their skills.
- Keep localized pairs, QA versions/changelogs and `catalog.yml` consistent. English uses the base
  name and `language: en`; Chinese adds `-cn` and `language: zh-CN`. Paired `translation_of` values
  name each other. Translate prose while preserving commands, safety gates and observable behavior.
  The repository `VERSION` and each skill's QA version have separate scopes.
- Run `./tools/validate-all.sh` before reporting completion. This validates install payloads, not
  unexecuted behavioral or live-service scenarios.
- Run `./tools/install-git-hooks.sh` once per checkout. Ignore rules and commit/push/CI hygiene checks
  keep local-only files out of Git, including files added with force.
- Commit and publish only within user authorization. ClawHub receives English payloads only;
  GitHub retains both languages. Verify remote contents before announcing a release.
- Treat credentials, local installs and caches as local-only. Keep only the current release notes;
  rewriting Git history or deleting remote releases requires explicit user authorization.

## Concept-specific rules

- `catalog.yml` is the discovery source of truth. After catalog changes, run
  `python3 tools/skill-catalog.py --write`; the validation gate checks generated README sections and `skills.sh.json`.
- Keep one shared concept/specification contract across the Software Concept Architect family;
  run `tools/sync-concept-contract.py` through the normal QA gate.
- Keep QA and generated artifacts outside install payloads. Create pairs with
  `tools/skill-scaffold.sh <name>`, then register them in `catalog.yml`.