eliteforge-skill-spec

What this skill does

# EliteForge Skill Spec

## Required Skill-Creator Flow

1. Activate and follow `skill-creator` for every new skill and every substantial skill update.
2. For new skills, initialize with the `skill-creator` `scripts/init_skill.py` workflow unless the skill folder already exists.
3. Keep `SKILL.md` concise and authoritative. Put mandatory agent behavior in `SKILL.md`; use `references/` only for details loaded on demand.
4. Keep `agents/openai.yaml` aligned with the final `SKILL.md`.
5. Before finishing, run the `skill-creator` validator. If the validator is unavailable or fails for reasons unrelated to the current change, report the blocker instead of claiming validation success.

## Frontmatter Contract

Every `eliteforge-*` skill must declare `metadata.version` in the YAML frontmatter at the top of `SKILL.md`.

Minimum required shape:

```yaml
---
name: eliteforge-example
description: Example description.
metadata:
  version: 1.0.0
---
```

Rules:

- `metadata.version` is mandatory for every new `eliteforge-*` skill.
- When updating an existing `eliteforge-*` skill that does not yet have `metadata.version`, add it as part of the change.
- Keep `version` inside frontmatter `metadata`; do not move it to `agents/openai.yaml`, references, or body text.
- Use semantic version text in `MAJOR.MINOR.PATCH` form, such as `1.0.0`.
- If frontmatter already has other metadata fields, keep them and add `version` alongside them.

## Environment Variable Contract

Every `eliteforge-*` skill that uses user-configurable environment variables must declare them in the top-level `SKILL.md` under a fixed `## Environment Variables` section. Do not rely on declarations hidden in `references/`, `assets/`, scripts, examples, or `agents/openai.yaml`.

Use exactly one bullet per variable. The variable name itself must be in `SCREAMING_SNAKE_CASE` (uppercase, underscores as separators). Do not write `,SCREAMING_SNAKE_CASE` as part of the variable name — that notation only indicates the naming convention, not literal text.

```md
- `ELITEFORGE_SKILL_POSEIDON_BASE_URL` [optional] Description.
- `ELITEFORGE_SKILL_QINGTUI_APPID` [required] Description.
- `ELITEFORGE_SKILL_POSEIDON_AUTH_APP_ID` [conditional] Required when `ELITEFORGE_SKILL_POSEIDON_AUTH_TYPE=API_TOKEN`. Description.
```

Rules:

- The variable name must follow the format `ELITEFORGE_SKILL_<SKILL_ABBREV>_<PURPOSE>` in `SCREAMING_SNAKE_CASE`, where `SKILL_ABBREV` is the skill name stripped of the `eliteforge-` prefix, shortened for readability, then uppercased (e.g. `qingtui-cli` → `QINGTUI`, `poseidon-cli` → `POSEIDON`, `git-feature-oriented-spec` → `GIT`, `java-uml` → `JAVA_UML`, `agent-doctor` → `DOCTOR`), and `PURPOSE` is the variable's semantic purpose in `SCREAMING_SNAKE_CASE`.
- The requirement marker must be exactly `[optional]`, `[required]`, or `[conditional]`.
- `[required]` means the skill cannot run correctly unless the variable is configured.
- `[conditional]` means the variable is required only when the condition in the description is active.
- Conditional descriptions must include a machine-readable condition like `` `ELITEFORGE_SKILL_POSEIDON_AUTH_TYPE=API_TOKEN` ``.
- `[optional]` variables may affect defaults, output location, agent choice, or command convenience, but must not block readiness.
- Do not print secret values in skill output, reports, validation logs, or examples.

If a skill does not use user-configurable environment variables, omit the section.

## Output Path Contract

Every `eliteforge-*` skill that writes user-facing artifacts to the workspace must declare the path contract in the top-level `SKILL.md` under a fixed `## Output Path` section. Do not hide output path rules only in `references/`, `assets/`, scripts, examples, or `agents/openai.yaml`.

Use the section to define the primary source artifact path first. For example:

```md
## Output Path

Resolve the Typst source path in this order:

1. explicit user-provided path for the current task
2. `ELITEFORGE_SKILL_PRD_OUTPUT_PATH`
3. `<project>/docs/prd.typ`
```

Rules:

- Omit the section only when the skill does not write workspace artifacts.
- The section must resolve the primary output path in explicit priority order.
- If an environment variable participates in path resolution, declare the same variable in `## Environment Variables`.
- Document normalization rules when relevant, such as directory input handling, required file suffixes, and parent-directory creation.
- If the skill also emits derived artifacts, define them relative to the primary source artifact path and identify the source-of-truth file.
- Keep the section artifact-specific and concise; describe only the paths the skill actually writes.

## Agent-Doctor Contract

`eliteforge-agent-doctor` is the environment readiness scanner for this contract. It must:

- scan only top-level `skills/eliteforge-*/SKILL.md` files by default
- parse only declarations inside each top-level `## Environment Variables` section
- report unset variables in three categories: `missing_required`, `missing_conditional`, and `optional_unset`
- treat only `missing_required` and active `missing_conditional` entries as readiness blockers
- ignore variable mentions in references, templates, command examples, and scripts unless the same variable is declared in top-level `SKILL.md`

## Review Checklist

When reviewing a skill change:

- Confirm YAML frontmatter contains `metadata.version`.
- Confirm mandatory rules are in `SKILL.md`, not only in references.
- Confirm every user-configurable environment variable has a compliant top-level declaration.
- Confirm every skill that writes workspace artifacts has a compliant top-level `## Output Path` section.
- Confirm optional environment variables have safe defaults or documented fallback behavior.
- Confirm required or conditional secret variables are never echoed.
- Run `skill-creator` validation before final response.