Agent Skills › hao-ai-lab/FastVideo › env-var-conventions

env-var-conventions

GitHub

管理FastVideo环境变量注册、读取及策略变更，确保符合规范并通过契约测试。

.agents/skills/env-var-conventions/SKILL.md hao-ai-lab/FastVideo

Trigger Scenarios

修改或新增环境变量环境变量策略变更环境政策契约测试失败

Install

npx skills add hao-ai-lab/FastVideo --skill env-var-conventions -g -y

More Options

Non-standard path

npx skills add https://github.com/hao-ai-lab/FastVideo/tree/main/.agents/skills/env-var-conventions -g -y

Use without installing

npx skills use hao-ai-lab/FastVideo@env-var-conventions

指定 Agent (Claude Code)

npx skills add hao-ai-lab/FastVideo --skill env-var-conventions -a claude-code -g -y

安装 repo 全部 skill

npx skills add hao-ai-lab/FastVideo --all -g -y

预览 repo 内 skill

npx skills add hao-ai-lab/FastVideo --list

SKILL.md

Frontmatter

{
    "name": "env-var-conventions",
    "description": "Add, read, rename, or remove an environment variable in FastVideo, or change the environment-variable policy. Use before touching fastvideo\/envs.py, os.environ, os.getenv, or monkeypatch.setenv in fastvideo\/, and when fastvideo\/tests\/contract\/test_env_policy.py fails."
}

Environment Variable Conventions

Purpose

FastVideo registers its environment variables as typed fields in fastvideo/envs.py. The policy that governs them is docs/contributing/env_vars.md, and the contract test fastvideo/tests/contract/test_env_policy.py enforces the policy in the unit CI lane. This skill routes an environment-variable change through that policy. The policy doc is the single source of the rules; read it instead of relying on a summary here.

Prerequisites

Read docs/contributing/env_vars.md in full.
Decide whether the setting belongs in an environment variable or an argument (rule 5 in the policy doc). Settings that users change per deployment are arguments; add them through fastvideo/fastvideo_args.py instead.

Inputs

Parameter	Required	Description
`change`	Yes	Add, read, rename, or remove a variable, or change the policy.
`variable`	Yes	The variable name, with the `FASTVIDEO_` prefix.

Steps

Declare or edit the variable in fastvideo/envs.py.
- Pick the field type and category that the policy doc lists.
- Write a description that states what the variable does and its units.
- To rename, keep the old name in deprecated_names. To remove, add the name to DEPRECATED_VARIABLES. Update the uses in examples/, scripts/, docs/, apps/, and the tests.
Read the variable with envs.NAME.get() inside a function.
- In tests, change the value with envs.NAME.override(value), and a variable outside the registry with envs.override_external(name, value); the env_overrides fixture keeps either until the end of the test.
- Name a variable that only tests read FASTVIDEO_TEST_*.
- Do not call os.environ, os.getenv, or monkeypatch.setenv for a FastVideo variable.
- To set a variable that another tool reads, call envs.set_external, envs.setdefault_external, or envs.unset_external.
Regenerate the table in the policy doc.
- Run python fastvideo/tests/contract/test_env_policy.py.
Run the contract test.
- Run pytest fastvideo/tests/contract/test_env_policy.py.
- When the test reports a fixed known violation, delete or lower its entry in KNOWN_VIOLATIONS. Never add an entry to KNOWN_VIOLATIONS.
When the policy itself changes, update the policy doc and the contract test in the same pull request.
- The rules in docs/contributing/env_vars.md, the checks and allowlist in fastvideo/tests/contract/test_env_policy.py, and this skill must agree.

Outputs

A registry entry in fastvideo/envs.py and call sites that use envs.NAME.get().
A regenerated table in docs/contributing/env_vars.md.
A passing fastvideo/tests/contract/test_env_policy.py.

Example Usage

Add a FASTVIDEO_DEBUG_MY_STAGE switch that logs MyStage inputs.

References

docs/contributing/env_vars.md: the policy, the field types, and the violation kinds that the contract test reports.
fastvideo/envs.py: the registry.
fastvideo/tests/contract/test_env_policy.py: the contract test, EXTERNAL_ALLOWLIST, and KNOWN_VIOLATIONS.