references

# Skill Reference

## CLI Commands

### Discovery

```bash
# List skill packages
refly skill list [options]
  --status <status>     # Filter: draft, published, deprecated
  --mine                # Show only my packages
  --tags <tags>         # Filter by tags (comma-separated)
  --page <number>       # Page number (default: 1)
  --page-size <number>  # Page size (default: 20)

# Search public packages
refly skill search <query> [options]
  --tags <tags>         # Filter by tags (comma-separated)
  --page <number>       # Page number (default: 1)
  --page-size <number>  # Page size (default: 20)

# Get skill details
refly skill get <skillId> [options]
  --include-workflows   # Include workflow details
  --share-id <shareId>  # Share ID for private skills
```

### Lifecycle

```bash
# Create skill package (see "Skill Creation Modes" below)
refly skill create [options]
  --name <name>                 # Skill name (required)
  --version <version>           # Semantic version (default: 1.0.0)
  --description <desc>          # Skill description
  --triggers <triggers>         # Trigger phrases (comma-separated)
  --tags <tags>                 # Category tags (comma-separated)
  --workflow <workflowId>       # Bind single workflow
  --workflow-ids <ids>          # Bind multiple workflows (comma-separated)
  --workflow-spec <json>        # Workflow spec JSON
  --workflow-query <query>      # Natural language description
  --verbose                     # Include workflow details in output

# Publishing
refly skill publish <skillId>   # Make public
refly skill unpublish <skillId> # Make private
refly skill delete <skillId> [options]
  --force                       # Skip confirmation

# Local management
refly skill sync [options]      # Sync registry with filesystem
  --dry-run                     # Preview changes only
  --prune                       # Remove orphan entries

refly skill validate [path] [options]
  --fix                         # Attempt to fix issues
```

### Installation

```bash
# Install skill
refly skill install <skillId> [options]
  --version <version>   # Specific version
  --share-id <shareId>  # Share ID for private skills
  --config <json>       # Installation config JSON

# List installations
refly skill installations [options]
  --status <status>     # Filter: downloading, initializing, ready, error, disabled
  --page <number>       # Page number (default: 1)
  --page-size <number>  # Page size (default: 20)

# Uninstall
refly skill uninstall <installationId> [options]
  --force               # Skip confirmation
```

### Execution

```bash
# Run installed skill
refly skill run <installationId> [options]
  --input <json>                # Input JSON for the skill
  --workflow <skillWorkflowId>  # Run specific workflow only
  --async                       # Run asynchronously
```

---

## Skill Creation Modes

### Mode 1: Generate Workflow from Query

```bash
refly skill create --name <name> --workflow-query "<query>"
```

Behavior:
1. Calls backend AI to generate workflow
2. Creates skill and binds workflow
3. Returns skillId + workflowId

Optional metadata (does not generate workflow by itself):
- `--description`, `--triggers`, `--tags`

Example:
```bash
refly skill create \
  --name comfyui-refly-skill \
  --workflow-query "ComfyUI image generation workflow collection" \
  --description "ComfyUI image workflow collection" \
  --triggers "comfyui,text to image,image generation,image to image" \
  --tags "image,comfyui"
```

### Mode 2: Bind Existing Workflow(s)

```bash
refly skill create --name <name> --workflow <workflowId>
```

Bind multiple workflows:
```bash
refly skill create --name <name> --workflow-ids "<workflowId1,workflowId2>"
```

Example:
```bash
refly skill create \
  --name my-skill \
  --description "My custom skill" \
  --workflow c-zybbx65ydi5npo7xevjx1wlr \
  --triggers "custom,workflow" \
  --tags "internal"
```

### Mode 3b: Bind Multiple Workflows (Explicit)

```bash
refly skill create --name <name> --workflow-ids "<workflowId1,workflowId2>"
```

Example:
```bash
refly skill create \
  --name multi-workflow-skill \
  --description "Multiple workflow entry points" \
  --workflow-ids "c-aaa111,c-bbb222" \
  --triggers "multi,entry" \
  --tags "batch,workflow"
```

### Mode 3: Use Workflow Spec (Structured)

```bash
refly skill create --name <name> --workflow-spec '<json>'
```

Example:
```bash
refly skill create \
  --name pdf-processor \
  --workflow-spec '{
    "nodes": [
      {"id": "n1", "type": "start", "data": {"title": "Start"}},
      {"id": "n2", "type": "skillResponse", "data": {"title": "Process PDF", "metadata": {"query": "Extract and summarize PDF content"}}}
    ],
    "edges": [
      {"id": "e1", "source": "n1", "target": "n2"}
    ]
  }'
```

> **Note**: Examples use `start` and `skillResponse`. Additional node types may be supported by backend.

### Mode 4: Local Skill Only (No Cloud Package)

Use when you only want a local skill directory and registry entry.

```bash
# Create local skill files manually, then sync
refly skill sync
```

You can later create a cloud skill package with:
```bash
refly skill create --name <name> --workflow <workflowId>
```

---

## Workflow Generation Logic

When no `--workflow`, `--workflow-ids`, `--workflow-spec`, or `--workflow-query` is specified,
CLI will return `skill.create.needs_workflow` with suggested options and examples.

---

## Directory Structure

```
~/.refly/skills/
├── base/                       # Base skill files (symlink target for 'refly')
│   ├── SKILL.md
│   └── rules/
│       ├── workflow.md
│       ├── node.md
│       ├── file.md
│       └── skill.md
└── <skill-name>/               # Domain skill directories
    └── SKILL.md

~/.claude/skills/
├── refly → ~/.refly/skills/base/           # Base skill symlink
└── <skill-name> → ~/.refly/skills/<name>/  # Domain skill symlinks
```

### How Symlinks Work

- **Base skill**: `~/.claude/skills/refly` → `~/.refly/skills/base/`
- **Doma