richfrem/create-agentic-workflow

[!IMPORTANT] CRITICAL POKA-YOKE RULE: NEVER hand-author or hand-edit .github/agents/*.agent.md or .github/workflows/*.md frontmatter. ALL generation MUST go through scaffold_github_agent.py. To change tools, engines, or triggers, re-run the scaffolder with the appropriate flag — do not edit the files by hand.

Follow the create-agentic-workflow skill workflow to convert a local skill into a GitHub-native agentic configuration (Target A, B, or C).

Inputs

• $1 (or --skill-dir) — path to the existing skill directory to convert
• --target — target type: A (Custom Copilot Agent .agent.md), B (GitHub Agentic Workflow gh-aw), or C (CI/CD Smart Failure agent)
• --name — custom name for the generated agent/workflow
• --engine — engine to use: copilot (default), claude, or codex
• --tools — comma-separated tools to allow (e.g. github,terminal or "" for none)

Steps

1. Resolve Input Skill: Confirm the source skill directory contains a valid SKILL.md.
2. Progressive Discovery (Interactive Interview):
   • Target Mode: Ask the user to select Target A, B, or C. Smart-default Target B (gh-aw) if the user says "runs in GitHub".
   • Trigger Event: Define the events (push, pull_request, schedule, issues, release) or schedule details.
   • AI Engine: Select copilot (default), claude, or codex.
   • Safe Outputs / Write Operations (Target B): Define allowed write actions (e.g. add-comment, create-issue, add-labels).
   • MCP Servers & Tooling (Target A): Identify which tools/MCP servers to grant permission to.
3. Recap Gate: Present a summary of the configuration. Ask the user: "Does this look right? yes / adjust". Proceed only on confirmation.
4. Scaffolder Execution: Run scaffold_github_agent.py to write the target files.
5. Validation & Compilation Gate:
   • Run validate_github_agent.py to verify schema compliance.
   • Accuracy Caveat: For Target B, since gh-aw is in public preview and frontmatter schemas may drift, ALWAYS attempt to compile using gh aw compile after generation and treat compile errors as the source of truth over templates.

Output

Generated agent metadata, prompt companion files, workflow YAMLs, or markdown configurations depending on target selection:

• Target A:
  • .github/agents/<name>.agent.md (Main agent config)
  • .github/prompts/<name>.prompt.md (System prompt stub)
• Target B:
  • .github/workflows/<name>.md (Only file produced by scaffolder. Note: the companion .github/workflows/<name>.lock.yml must be generated by running gh aw compile, not the scaffolder)
• Target C:
  • .github/agents/<name>.agent.md (CI/CD Smart Failure persona config)
  • .github/workflows/<name>-agent.yml (Runner workflow file)

Edge Cases

• Target B Compilation: If gh-aw CLI is not installed locally, output warning and instructions for gh extension install github/gh-aw.
• Target C Kill Switch: Ensure the custom Kill Switch phrase appears verbatim in both the .agent.md body and the workflow runner's grep condition, along with the Escalation Trigger Taxonomy.
• Tools Frontmatter Difference: Highlight that Target A uses standard GitHub agent frontmatter keys (e.g., tools: [github, terminal]), NOT the Claude-style frontmatter keys (e.g., permissions.allowedTools) generated by create-sub-agent.