Gitea-Tools/docs/workflow-skill-mount.md

Workflow skill mount across runtimes (#551)

Problem

Controller prompts require gitea-workflow, but:

• Claude may load ~/.claude/skills/gitea-workflow
• Codex often has no ~/.codex/skills/gitea-workflow
• The portable package in-repo is skills/llm-project-workflow
• mcp_list_project_skills historically listed operational guides only, not the workflow router

Sessions then either block incorrectly or proceed without the workflow wall.

Canonical names (must resolve to the same skill)

Name	Use
gitea-workflow	Primary controller / Codex skill name
llm-project-workflow	Portable in-repo package name
git-pr-workflows	Legacy alias

Source of truth: skills/llm-project-workflow/SKILL.md
In-repo alias stub: skills/gitea-workflow/SKILL.md

Codex install

From a branches/ worktree (or any clone of the repo):

./scripts/install-codex-workflow-skill.sh
# optional:
./scripts/install-codex-workflow-skill.sh --dry-run
./scripts/install-codex-workflow-skill.sh --skills-dir "$HOME/.codex/skills"

This symlinks the portable package under all three names. Restart Codex after install.

MCP discovery

• mcp_list_project_skills includes gitea-workflow, llm-project-workflow, and git-pr-workflows.
• mcp_get_skill_guide("<name>") returns the same router steps for each.
• mcp_check_workflow_skill_preflight proves the in-repo skill file exists and reports Codex mount status.

Preflight rule

Before any git or Gitea mutation:

1. Call mcp_check_workflow_skill_preflight.
2. If blocked / workflow_skill_ready is false → BLOCKED + DIAGNOSE; do not mutate.
3. Load the skill by any canonical name and follow the router.

Missing Codex mount alone does not block if the in-repo skill is present and loaded via MCP/docs; operators should still install the Codex symlink so prompt names resolve natively.

Controller prompts

Prefer:

Invoke skill gitea-workflow (alias of llm-project-workflow).

Do not require a name that is only available on one runtime.