SkillAgentSearch skills...

references

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

Install / Use

npx skills add refly-ai/refly --skill references

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

92/100

Category

Automation

Supported Platforms

Universal

Tags

Our assessment of references

references scores 92/100 on our quality scale, 818th of 2,790 Automation skills we index (top 30%).

Its SKILL.md is 10 KB long, well organised into 40 sections with 22 code examples: a thorough specification that gives an agent plenty to work with.

With 7,554 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
17/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 14 days ago, so references is actively maintained.
  • Our last check on 2026-10-05 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-26. Automated pattern scan on 2026-09-26. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

references compared with similar skills

All 4 of these similar skills score higher than references; compare them before choosing.

SkillScoreStarsUpdatedFormat
references (this skill)by refly-ai927.6k14d agoSKILL.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.md
Scraplingby D4Vinci100103.6k2d agoMCP Server

Frequently asked questions

How do I install references?
Run npx skills add refly-ai/refly --skill references. The install tabs above show the steps for each supported agent.
Which AI agents does references work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is references safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is references still maintained?
The repository was last updated 14 days ago, so references is actively maintained.

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:

  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:

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:

  1. Be specific in workflow query - helps AI generate accurate workflow
  2. Include diverse triggers - cover EN/ZH variations
  3. Test before publish - install then run (refly skill install -> refly skill run)
  4. 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:

  1. Create cloud skill -> refly skill create (generates workflow + local symlink)
  2. Publish skill -> refly skill publish -> makes skill discoverable
  3. Install to run -> refly skill install -> creates local SKILL.md + symlink
  4. 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.

Related Skills

View on GitHub
GitHub Stars7.6k
CategoryAutomation
Updated14d ago
Forks726

Languages

TypeScript

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium