---
name: readme-capability-badges
description: Design static Shields.io README badges for repository capability signals, especially deployment capability labels such as image publish, manual deploy to dev/prod, and automatic deploy to dev/prod. Use when Codex needs to inspect repository GitHub Actions workflows, including image build/push workflows and OOMOL aliyun-deploy-action workflows, and propose, standardize, or edit README badges that describe what a repository can do, not live CI or GitHub Actions run status.
metadata:
  packageName: '@leavesster/readme-capability-badges'
  version: 0.0.1
---

# Readme Capability Badges

## Overview

Use this skill to express repository capabilities as stable README badges. Keep the badges semantic and human-scannable: they should describe whether a capability exists and how it is triggered, not whether the latest run passed.

## Design Rules

- Prefer Shields.io static badge URLs.
- Use short labels: `image publish`, `dev deploy`, `prod deploy`, `preview env`, `rollback`.
- Use short values: `auto`, `manual`, `enabled`, `partial`, `none`.
- Include both label and value in image alt text, preferably as `label: value`, so raw Markdown still communicates the capability. For example, use `![dev deploy: auto](...)`, not `![dev deploy](...)`.
- Do not use these badges for CI status. Use GitHub Actions workflow badges for live run state.
- Keep each badge to one meaning. Do not combine environment and unrelated behavior in one badge.
- Use lowercase badge text unless matching an existing README style.
- URL-encode spaces as `%20`; encode hyphen-like separators in labels with `--` only when using Shields' dash syntax.

## Image Publish Badges

Use this badge when repository workflows can build and push a container image, but do not prove that the image is deployed to a runtime environment:

```md
![image publish: auto](https://img.shields.io/badge/image%20publish-auto-brightgreen)
![image publish: manual](https://img.shields.io/badge/image%20publish-manual-blue)
```

Meanings:

- `image publish: auto`: the repository automatically publishes a container image from a configured event such as push, tag, release, or another non-manual trigger.
- `image publish: manual`: the repository can publish a container image, but it must be manually triggered.

Detect image publish capability from `.github/workflows/*.yml` and `.github/workflows/*.yaml` by looking for workflows that push images to a registry. Common signals include:

- `docker/build-push-action` with `push: true`
- `docker buildx build --push`, `docker push`, `docker manifest push`, or `docker buildx imagetools create`
- registry login plus a later push to GHCR, ACR, ECR, GCR/Artifact Registry, Docker Hub, or another container registry

Classify trigger mode using the same trigger rules as deployment badges: any non-`workflow_dispatch` trigger is `auto`; only `workflow_dispatch` is `manual`; both together means `auto`.

Keep image publication separate from deployment. An image push workflow proves that an artifact is published, not that dev or prod was updated. Only add `dev deploy` or `prod deploy` badges when a workflow actually targets an environment deploy or rollout path.

## Deployment Badges

Use this vocabulary:

```md
![dev deploy: manual](https://img.shields.io/badge/dev%20deploy-manual-blue)
![prod deploy: manual](https://img.shields.io/badge/prod%20deploy-manual-yellow)

![dev deploy: auto](https://img.shields.io/badge/dev%20deploy-auto-brightgreen)
![prod deploy: auto](https://img.shields.io/badge/prod%20deploy-auto-orange)
```

Meanings:

- `dev deploy: manual`: the repository has an action/workflow that can deploy to dev, but it must be manually triggered.
- `prod deploy: manual`: the repository has an action/workflow that can deploy to production, but it must be manually triggered.
- `dev deploy: auto`: the repository automatically deploys to dev from a configured event such as push, merge, tag, or release.
- `prod deploy: auto`: the repository automatically deploys to production from a configured event.

Default color choices:

- `auto` to dev: `brightgreen`
- `manual` to dev: `blue`
- `manual` to prod: `yellow`
- `auto` to prod: `orange`
- unavailable or intentionally absent: `lightgrey` or `red`, depending on whether absence is neutral or a warning.

## OOMOL Aliyun Deploy Detection

When a repository uses workflows generated by `$aliyun-deploy-action`, derive the badges from `.github/workflows/*.yml` and `.github/workflows/*.yaml`.

Recognize these central reusable workflows:

- Dev image deploy: `oomol/aliyun-k8s-yaml/.github/workflows/reusable-trigger-central-dev-image-deploy.yaml@main`
- Prod image deploy: `oomol/aliyun-k8s-yaml/.github/workflows/reusable-trigger-central-prod-image-deploy.yaml@main`
- Deployment rollout: `oomol/aliyun-k8s-yaml/.github/workflows/reusable-trigger-central-deployment-rollout.yaml@main` with `with.environment: dev` or `with.environment: prod`

Classify each environment independently:

- For `dev`, inspect only workflows that target dev image deploy or rollout with `environment: dev`.
- For `prod`, inspect only workflows that target prod image deploy or rollout with `environment: prod`.
- If any matching workflow for that environment has an automatic trigger, badge that environment as `auto`.
- Otherwise, if any matching workflow for that environment has `workflow_dispatch`, badge that environment as `manual`.
- Otherwise, badge that environment as `none` only when the README should explicitly show absence; usually omit absent environments unless the user asks for a complete matrix.

Treat these as automatic triggers:

- `push`
- `pull_request`
- `pull_request_target`
- `release`
- `workflow_run`
- `schedule`
- any other non-`workflow_dispatch` trigger that can run without a person clicking Run workflow

Treat `workflow_dispatch` as manual. If a workflow has both `workflow_dispatch` and an automatic trigger, classify it as `auto`.

Preserve operation independence from environment independence. `image-deploy` and `deployment-rollout` both prove deploy capability for the target environment; the badge only reports trigger mode for that environment, not the operation type.

## Common Sets

Image publish only, no proven deploy capability:

```md
![image publish: auto](https://img.shields.io/badge/image%20publish-auto-brightgreen)
```

Manual deploy to both environments:

```md
![dev deploy: manual](https://img.shields.io/badge/dev%20deploy-manual-blue)
![prod deploy: manual](https://img.shields.io/badge/prod%20deploy-manual-yellow)
```

Auto deploy to dev, manual deploy to production:

```md
![dev deploy: auto](https://img.shields.io/badge/dev%20deploy-auto-brightgreen)
![prod deploy: manual](https://img.shields.io/badge/prod%20deploy-manual-yellow)
```

Auto deploy to both environments:

```md
![dev deploy: auto](https://img.shields.io/badge/dev%20deploy-auto-brightgreen)
![prod deploy: auto](https://img.shields.io/badge/prod%20deploy-auto-orange)
```

No production deploy capability:

```md
![dev deploy: auto](https://img.shields.io/badge/dev%20deploy-auto-brightgreen)
![prod deploy: none](https://img.shields.io/badge/prod%20deploy-none-lightgrey)
```

## Editing READMEs

When editing an existing README, inspect nearby badge style first and match it unless it is ambiguous or misleading. Place capability badges near the top, usually below the title and before longer prose. If existing badges already show live build/test status, keep capability badges visually separate by label wording rather than by adding explanatory text.