eliteforge-skill-spec

name	eliteforge-skill-spec
description	EliteForge skill authoring specification for creating or modifying eliteforge-* skills. Use when users create a new EliteForge skill, modify an existing EliteForge skill, review skill structure, add or change skill environment variables or output path rules, or need to validate SKILL.md/frontmatter/agents metadata with skill-creator.
metadata	{"version":"1.0.1"}

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:

---
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.

- `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:

## 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.