Refly references

Skill Reference

install

source · Clone the upstream repo

git clone https://github.com/refly-ai/refly

manifest: packages/cli/skill/references/skill.md

source content

Skill Reference

CLI Commands

Discovery

# 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

# 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

# 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

# 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

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

Behavior:

Calls backend AI to generate workflow
Creates skill and binds workflow
Returns skillId + workflowId

Optional metadata (does not generate workflow by itself):

```
--description
```
,
```
--triggers
```
,
```
--tags
```

Example:

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)

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

Bind multiple workflows:

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

Example:

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

Mode 3b: Bind Multiple Workflows (Explicit)

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

Example:

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)

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

Example:

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.

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

You can later create a cloud skill package with:

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/

Domain skills:

~/.claude/skills/<name>

→

~/.refly/skills/<name>/

Claude Code discovers skills via symlinks in

~/.claude/skills/

. Each skill is a symlink pointing to the actual skill directory in

~/.refly/skills/

Domain Skill Template

Location:

~/.refly/skills/<skill-name>/SKILL.md

(accessed via

~/.claude/skills/<skill-name>/SKILL.md

)

---
name: <skill-name>
description: <one-line summary, under 100 chars>
workflowId: <workflow-id>
triggers:
  - <phrase-1>
  - <phrase-2>
tags:
  - <tag-1>
author: <author>
version: 1.0.0
---

# <Skill Name>

## Quick Start

<Minimal code example>

## Run

```bash
refly skill run <installationId> --input '<json>'
```

## Advanced

**Feature A**: See [FEATURE_A.md](FEATURE_A.md)
**API Reference**: See [REFERENCE.md](REFERENCE.md)

Best Practices

Naming: lowercase, hyphens, max 64 chars (

pdf-processing

doc-translator

)

Description: verb + what + when, third person, under 100 chars

Good: "Extracts text from PDF files. Use when processing PDF documents."
Bad: "I can help you with PDFs"

Triggers: 3-6 high-signal phrases, mix EN/ZH if needed

Structure: Each skill is a directory with

skill.md

as entry; push details to sibling files

Workflow Creation:

Be specific in workflow query - helps AI generate accurate workflow
Include diverse triggers - cover EN/ZH variations
Test before publish - install then run (
```
refly skill install
```
->
```
refly skill run
```
)
Use
```
--workflow-spec
```
for complex scenarios requiring precise control

Local Skills vs Cloud Skills

Type	Location	Management	Use Case
Local	`~/.refly/skills/<name>/`	Symlinks	Fast iteration
Cloud	Backend `SkillPackage`	API	Distribution & versioning

Integration flow:

Create cloud skill ->
```
refly skill create
```
(generates workflow + local symlink)
Publish skill ->
```
refly skill publish
```
-> makes skill discoverable
Install to run ->
```
refly skill install
```
-> creates local SKILL.md + symlink
Run skill ->
```
refly skill run <installationId>
```

Output Examples

List Output

{
  "ok": true,
  "type": "skill.list",
  "version": "1.0",
  "payload": {
    "skills": [
      {
        "skillId": "skp-xxx",
        "name": "my-skill",
        "version": "1.0.0",
        "description": "Skill description",
        "status": "published",
        "isPublic": true,
        "downloadCount": 10,
        "createdAt": "2026-01-19T00:00:00Z"
      }
    ],
    "total": 10,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}

Installations Output

{
  "ok": true,
  "type": "skill.installations",
  "version": "1.0",
  "payload": {
    "installations": [
      {
        "installationId": "skpi-xxx",
        "skillId": "skp-xxx",
        "skillName": "my-skill",
        "skillVersion": "1.0.0",
        "status": "ready",
        "installedAt": "2026-01-19T00:00:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}

Execution Output

{
  "ok": true,
  "type": "skill.run",
  "version": "1.0",
  "payload": {
    "executionId": "skpe-xxx",
    "installationId": "skpi-xxx",
    "status": "completed",
    "workflowExecutions": [
      {
        "skillWorkflowId": "skw-xxx",
        "workflowId": "c-xxx",
        "status": "completed"
      }
    ],
    "result": {},
    "error": null
  }
}

Skill Sync Details

refly skill sync

will:

Validate existing symlinks in
```
~/.claude/skills/
```
Check for broken symlinks (pointing to non-existent directories)
Check for orphan directories (directories without symlinks)
With
```
--fix
```
: recreate broken symlinks
With
```
--prune
```
: remove broken symlinks

Skill Validate Details

refly skill validate [path]

will:

Validate frontmatter schema and required fields
Return per-file errors and warnings
Provide a summary of valid/invalid files

Example output:

{
  "ok": true,
  "type": "skill.validate",
  "version": "1.0",
  "payload": {
    "path": "/path/to/skills",
    "summary": {
      "total": 3,
      "valid": 2,
      "invalid": 1,
      "warnings": 1
    }
  }
}

Error Handling

Error Code	Cause	Solution
`VALIDATION_ERROR`	Missing required params or invalid format	Check `--name` and other required params
`ACCESS_DENIED`	No permission for resource	Verify login and resource ownership
`INTERNAL_ERROR`	Server error	Retry later or contact support

Note: Invalid JSON in
--workflow-spec
will fail the command; ensure it is valid JSON.