Workflows

# CreateSkill Workflow

Create a new skill following the canonical structure with proper TitleCase naming.

## Notification


Running the **CreateSkill** workflow in the **CreateSkill** skill to create new skill...

## Step 1: Read the Authoritative Sources

**REQUIRED FIRST:**

1. Read the skill system documentation: `~/.opencode/PAI/SKILLSYSTEM.md`
2. Read the canonical example: `~/.opencode/skills/_BLOGGING/SKILL.md`

## Step 2: Understand the Request

Ask the user:
1. What does this skill do?
2. What should trigger it?
3. What workflows does it need?

## Step 3: Determine TitleCase Names

**All names must use TitleCase (PascalCase).**

| Component | Format | Example |
|-----------|--------|---------|
| Skill directory | TitleCase | `Blogging`, `Daemon`, `CreateSkill` |
| Workflow files | TitleCase.md | `Create.md`, `UpdateDaemonInfo.md` |
| Reference docs | TitleCase.md | `ProsodyGuide.md`, `ApiReference.md` |
| Tool files | TitleCase.ts | `ManageServer.ts` |
| Help files | TitleCase.help.md | `ManageServer.help.md` |

**Wrong naming (NEVER use):**
- `create-skill`, `create_skill`, `CREATESKILL` → Use `CreateSkill`
- `create.md`, `CREATE.md`, `create-info.md` → Use `Create.md`, `CreateInfo.md`

## Step 3b: Probe the API Contract (MANDATORY for integration skills)

**If the skill talks to an API, establish the contract as fact before a single file is written.**

```bash
bun ~/.opencode/PAI/Tools/ApiProbe.ts \
  --base-url <url> --auth-env <ENV_VAR> [--auth-header X-API-Key] \
  --version-path /system/info --endpoints /a,/b,/c [--insecure]
```

The probe fetches the version first, smoke-tests the endpoints you name, and prints a dated **verified facts** block. Paste that block into the skill's docs — skill documentation carries only verified facts, with the date they were verified.

**Do not write the skill until every probe passes.** A failing probe is the cheapest signal available:

| Response | What it means | What to do |
|---|---|---|
| 401 / 403 | Credential scope, or this version dropped this transport | Check the version's docs before trying other headers. TrueNAS Fangtooth 25.04 deprecated REST for WebSocket JSON-RPC; header permutation cost 10+ rounds of 403 debugging |
| 404 | Wrong path, or a different payload convention | Read the OpenAPI spec or the handler source. **Never permute HTTP methods to find one that works** — a read-only API key is a preserved safety mechanism, and POST against system endpoints has halted a firewall here before |
| 400 | The payload encoding is wrong | Read the handler signature. Portainer's `POST /api/endpoints` takes multipart/form-data, not JSON — guessing field names wasted a round |

The one integration session that probed before building (Proxmox, 6 endpoints verified up front) finished with **zero rework**. The two that skipped it spent 10+ rounds and two hours respectively.

**Write calls are never part of a probe.** When the skill needs a write path, ask the principal first and document which channel is allowed (API, SSH, or Web UI) in the skill doc.

## Step 4: Create the Skill Directory

```bash
mkdir -p ~/.opencode/skills/[SkillName]/Workflows
mkdir -p ~/.opencode/skills/[SkillName]/Tools
```

**Example:**
```bash
mkdir -p ~/.opencode/skills/Daemon/Workflows
mkdir -p ~/.opencode/skills/Daemon/Tools
```

## Step 5: Create SKILL.md

Follow this exact structure:

```yaml
---
name: SkillName
description: [What it does]. USE WHEN [intent triggers using OR]. [Additional capabilities].
---

# SkillName

[Brief description]

## Notification

**When executing a workflow, output a text notification:**

```
Running **WorkflowName** in **SkillName**...
```

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **WorkflowOne** | "trigger phrase" | `Workflows/WorkflowOne.md` |
| **WorkflowTwo** | "another trigger" | `Workflows/WorkflowTwo.md` |

## Examples

**Example 1: [Common use case]**
```
User: "[Typical user request]"
→ Invokes WorkflowOne workflow
→ [What skill does]
→ [What user gets back]
```

**Example 2: [Another use case]**
```
User: "[Different request]"
→ [Process]
→ [Output]
```

## [Additional Documentation]

[Any other relevant info]
```

## Step 6: Create Workflow Files

For each workflow in the routing section:

```bash
touch ~/.opencode/skills/[SkillName]/Workflows/[WorkflowName].md
```

### Workflow-to-Tool Integration (REQUIRED for workflows with CLI tools)

**If a workflow calls a CLI tool, it MUST include intent-to-flag mapping tables.**

This pattern translates natural language user requests into appropriate CLI flags:

```markdown
## Intent-to-Flag Mapping

### Model/Mode Selection

| User Says | Flag | When to Use |
|-----------|------|-------------|
| "fast", "quick", "draft" | `--model haiku` | Speed priority |
| (default), "best", "high quality" | `--model opus` | Quality priority |

### Output Options

| User Says | Flag | Effect |
|-----------|------|--------|
| "JSON output" | `--format json` | Machine-readable |
| "detailed" | `--verbose` | Extra information |

## Execute Tool

Based on user request, construct the CLI command:

\`\`\`bash
bun ToolName.ts \
  [FLAGS_FROM_INTENT_MAPPING] \
  --required-param "value"
\`\`\`
```

**Why this matters:**
- Tools have rich configuration via flags
- Workflows should expose this flexibility, not hardcode single patterns
- Users speak naturally; workflows translate to precise CLI

**Reference:** `~/.opencode/PAI/CLIFIRSTARCHITECTURE.md` (Workflow-to-Tool Integration section)

**Examples (TitleCase):**
```bash
touch ~/.opencode/skills/Daemon/Workflows/UpdateDaemonInfo.md
touch ~/.opencode/skills/Daemon/Workflows/UpdatePublicRepo.md
touch ~/.opencode/skills/_BLOGGING/Workflows/Create.md
touch ~/.opencode/skills/_BLOGGING/Workflows/Publish.md
```

## Step 7: Verify TitleCase

Run this check:
```bash
ls ~/.opencode/skills/[SkillName]/
ls ~/.opencode/skills/[SkillName]/Workflows/
ls ~/.opencode/skills/[SkillName]/Tools/
```

Verify ALL files use TitleCase:
- `SKILL.md` ✓ (exception - always uppercase)
- `WorkflowName.md` ✓
- `ToolName.ts` ✓
- `ToolName.help.md` ✓

## Step 8: Final Checklist

### Naming (TitleCase)
- [ ] Skill directory uses TitleCase (e.g., `Blogging`, `Daemon`)
- [ ] All workflow files use TitleCase (e.g., `Create.md`, `UpdateInfo.md`)
- [ ] All reference docs use TitleCase (e.g., `ProsodyGuide.md`)
- [ ] All tool files use TitleCase (e.g., `ManageServer.ts`)
- [ ] Routing table workflow names match file names exactly

### YAML Frontmatter
- [ ] `name:` uses TitleCase
- [ ] `description:` is single-line with embedded `USE WHEN` clause
- [ ] No separate `triggers:` or `workflows:` arrays
- [ ] Description uses intent-based language
- [ ] Description is under 1024 characters

### Markdown Body
- [ ] `## Workflow Routing` section with table format
- [ ] All workflow files have routing entries
- [ ] `## Examples` section with 2-3 concrete usage patterns

### Structure
- [ ] `tools/` directory exists (even if empty)
- [ ] No `backups/` directory inside skill

### CLI-First Integration (for skills with CLI tools)
- [ ] CLI tools expose configuration via flags (see CliFirstArchitecture.md)
- [ ] Workflows that call CLI tools have intent-to-flag mapping tables
- [ ] Flag mappings cover: mode selection, output options, post-processing (where applicable)

## Done

Skill created following canonical structure with proper TitleCase naming throughout.