
looplia-core
Core workflow engine - Execute workflow-as-markdown definitions
- GitHub stars
- 21
Install
/plugin install looplia-core@loopliaRun it inside Claude Code after adding the marketplace with /plugin marketplace add memorysaver/looplia-core.
Contents
Discovered from sourceSkills 5
Registry Loader
Load the skill catalog for workflow building and skill discovery.
Purpose
Provides fast access to the skill catalog for the build pipeline.
Uses the pre-compiled ~/.looplia/registry/skill-catalog.json instead of runtime scanning.
Behavior
- Read the skill catalog from
~/.looplia/registry/skill-catalog.json - If catalog doesn't exist, return empty registry with instructions to run
looplia registry sync - Return catalog data for skill-capability-matcher
Process
1. Load Skill Catalog
Read the skill catalog file:
cat ~/.looplia/registry/skill-catalog.json
Or use the Read tool to access the file directly.
2. Parse Catalog Data
The skill catalog contains:
{
"compiledAt": "2026-01-04T12:00:00Z",
"version": "1.0.0",
"sources": [
{
"id": "official",
"type": "official",
"url": "https://github.com/memorysaver/looplia-core/releases/latest/download/registry.json",
"enabled": true,
"priority": 100
}
],
"skills": [
{
"name": "media-reviewer",
"title": "Media Reviewer",
"description": "Deep content analysis (structure, themes, narrative)",
"plugin": "looplia-writer",
"category": "analysis",
"capabilities": ["content-analysis", "media-processing"],
"tools": ["Read", "Grep", "Glob"],
"model": "claude-haiku-4-5-20251001",
"source": "local",
"sourceType": "builtin",
"installed": true,
"installedPath": "/home/user/.looplia/looplia-writer/skills/media-reviewer"
}
],
"summary": {
"totalSkills": 14,
"byCategory": {
"analysis": 3,
"generation": 2,
"assembly": 2,
"validation": 1,
"search": 1,
"orchestration": 3,
"utility": 2
},
"bySource": {
"local": 14
}
}
}
3. Format for skill-capability-matcher
Transform the skill catalog into the format expected by skill-capability-matcher:
{
"plugins": [
{
"name": "looplia-writer",
"path": "~/.looplia/looplia-writer",
"skills": [
{
"name": "media-reviewer",
"description": "Deep content analysis (structure, themes, narrative)",
"tools": ["Read", "Grep", "Glob"],
"model": "haiku",
"capabilities": ["content-analysis", "media-processing"],
"installed": true
}
]
}
],
"summary": {
"totalPlugins": 2,
"totalSkills": 14,
"installedSkills": 14,
"availableSkills": 0
}
}
Output Schema
{
"plugins": [
{
"name": "string",
"path": "string",
"skills": [
{
"name": "string",
"description": "string",
"tools": ["string"],
"model": "string",
"capabilities": ["string"],
"installed": "boolean"
}
]
}
],
"summary": {
"totalPlugins": "number",
"totalSkills": "number",
"installedSkills": "number",
"availableSkills": "number"
}
}
Advantages over plugin-registry-scanner
| Aspect | plugin-registry-scanner | registry-loader (v0.7.0) |
|---|---|---|
| Speed | Scans filesystem at runtime | Reads pre-compiled JSON |
| Sources | Local only | Official + third-party |
| Installation Status | Not tracked | Included in output |
| Third-party Skills | Not discovered | Included from remote registries |
Usage
This skill is typically invoked as the first step in workflow building:
- Load skill catalog (this skill)
- Pass catalog to skill-capability-matcher
- Use matched skills in workflow-schema-composer
Notes
- If skill catalog doesn't exist, advise user to run
looplia registry sync - Catalog is auto-synced on every
looplia buildcommand - Includes installation status for each skill
- Third-party skills may show
installed: falseuntil installed vialooplia skill add
Skill Capability Matcher
Match natural language requirements to available skills, designing an optimal workflow step sequence.
Purpose
Parse user's workflow description, understand their intent, and recommend which skills should handle each part of the workflow. Output includes step IDs, skill names, missions, and data flow.
Process
Step 1: Parse Requirements
Extract from the user's description:
Input Types:
- video transcript
- audio transcript
- article/blog post
- documentation
- raw text
- structured data (JSON/YAML)
Processing Goals:
- analyze (deep understanding)
- summarize (condensation)
- generate (create new content)
- transform (change format)
- extract (pull specific data)
- validate (check correctness)
Output Format:
- JSON structure
- Markdown document
- Summary text
- Structured data
Step 2: Load Registry
Read the plugin registry from registry-loader output (v0.7.0):
{
"plugins": [...],
"summary": { "totalSkills": N, "installedSkills": N, "availableSkills": N }
}
Build a capability index from skill descriptions and inferred capabilities.
Include installed status when scoring - prefer installed skills for immediate execution.
Step 3: Match Capabilities
Score each skill by:
- Description match - Does skill description align with requirements?
- Capability overlap - Do inferred capabilities match processing goals?
- Input/output compatibility - Can skill handle input type and produce expected output?
Step 4: Design Step Sequence
For each matched skill:
- Create a step ID (kebab-case, descriptive)
- Determine dependencies (
needs:) - Write a mission description (what to accomplish)
- Define data flow (input → output)
Step 5: Recommend Sequence
Order skills logically:
- Analysis skills first (understand content)
- Generation/transformation skills second
- Assembly/output skills last
Ensure proper data dependencies.
Step 6: Flag Gaps
If requirements can't be fully satisfied:
- List unmatched capabilities as gaps
- Suggest creating custom skills if needed
- Indicate if workflow is partial
Input
Provide:
- User's natural language description
- Registry JSON from plugin-registry-scanner
Output Schema
{
"requirements": {
"inputType": "video transcript",
"goals": ["extract key points", "generate outline"],
"outputFormat": "structured JSON"
},
"recommendations": [
{
"skill": "media-reviewer",
"suggestedStepId": "analyze-content",
"goalId": "analyze",
"matchScore": 0.92,
"capabilities": ["content analysis", "theme extraction"],
"mission": "Deep analysis of video transcript. Extract key themes, quotes, and narrative structure.",
"rationale": "Primary skill for content understanding"
},
{
"skill": "idea-synthesis",
"suggestedStepId": "generate-ideas",
"goalId": "generate",
"matchScore": 0.85,
"capabilities": ["idea generation", "hooks and angles"],
"mission": "Generate hooks, angles, and questions from the analysis. Read user profile for personalization.",
"rationale": "Creates engaging content ideas from analysis"
}
],
"suggestedSequence": ["analyze-content", "generate-ideas", "build-output"],
"dataFlow": {
"analyze-content": {
"needs": [],
"provides": "analysis.json"
},
"generate-ideas": {
"needs": ["analyze-content"],
"provides": "ideas.json"
},
"build-output": {
"needs": ["analyze-content", "generate-ideas"],
"provides": "output.json"
}
},
"gaps": [],
"customSkillNeeded": false,
"clarificationNeeded": true,
"clarifications": {
"sections": [
{
"id": "input",
"title": "Input",
"completed": false,
"questions": [
{
"id": "content-type",
"text": "What type of content will this workflow process?",
"type": "single-select",
"options": [
{ "id": "video", "label": "Video transcripts", "inferred": true },
{ "id": "audio", "label": "Audio transcripts" },
{ "id": "text", "label": "Text articles" },
{ "id": "web", "label": "Web pages (fetched via search)" }
],
"reason": "Inferred 'video' from description, confirm or change"
}
]
},
{
"id": "goals",
"title": "Goals",
"completed": false,
"questions": [
{
"id": "primary-goal",
"text": "What are the primary goals for this workflow?",
"type": "multi-select",
"options": [
{ "id": "analyze", "label": "Analyze and extract key insights" },
{ "id": "summarize", "label": "Create structured summaries" },
{ "id": "generate", "label": "Generate creative content ideas" },
{ "id": "document", "label": "Build comprehensive reports" }
]
},
{
"id": "depth",
"text": "How deep should the analysis be?",
"type": "single-select",
"options": [
{ "id": "quick", "label": "Quick overview (1-2 key points)" },
{ "id": "standard", "label": "Standard analysis (5-7 key points)" },
{ "id": "deep", "label": "Deep analysis (comprehensive)" }
]
}
]
},
{
"id": "output",
"title": "Output",
"completed": false,
"questions": [
{
"id": "format",
"text": "What output format do you need?",
"type": "single-select",
"options": [
{ "id": "json", "label": "Structured JSON" },
{ "id": "markdown", "label": "Markdown document" },
{ "id": "both", "label": "Both JSON and Markdown" }
]
}
]
},
{
"id": "review",
"title": "Review",
"completed": false,
"questions": []
}
]
}
}
Scoring Guidelines
| Match Type | Score |
|---|---|
| Exact capability match | 0.9-1.0 |
| Strong description overlap | 0.7-0.9 |
| Partial capability match | 0.5-0.7 |
| Weak/inferred match | 0.3-0.5 |
| No clear match | < 0.3 |
Scoring Rubric
Use these concrete criteria when assigning scores:
Relevance Score (Primary Factor)
- 90-100: Skill's primary purpose directly addresses requirement
- 70-89: Skill clearly capable of addressing requirement
- 50-69: Skill partially addresses requirement
- 30-49: Skill tangentially related
- 0-29: Minimal or no relevance
Completeness Score
- 90-100: Skill fully addresses all aspects of requirement
- 70-89: Skill addresses most aspects, minor gaps
- 50-69: Skill addresses core need, notable gaps
- Below 50: Significant portions unaddressed
Specificity Score
- 90-100: Skill specifically designed for this exact use case
- 70-89: Skill well-suited for use case category
- 50-69: General-purpose skill applicable to use case
- Below 50: Very general skill with broad applicability
Confidence Calculation
confidence = (relevance * 0.5) + (completeness * 0.3) + (specificity * 0.2)
Minimum threshold: 60% - Skills below this should not be recommended.
Semantic Matching Guidelines
Match requirements to skills beyond simple keyword matching:
1. Synonym Recognition
Match conceptually equivalent terms:
- "authentication" ↔ "login", "session management", "user verification"
- "database" ↔ "data persistence", "storage", specific ORMs
- "analyze" ↔ "review", "examine", "inspect", "assess"
- "generate" ↔ "create", "produce", "synthesize", "build"
2. Hierarchical Matching
Understand skill scope and specificity:
- General skill may satisfy specific requirement (e.g., "api-client" for "REST calls")
- Prefer specific skill over general when available (e.g., "stripe-integration" over "payment-api")
3. Intent Extraction
Focus on what user wants to accomplish, not just keywords:
- "I need to send emails" → match email/notification skills
- "Process video content" → match media-reviewer, not just skills with "video" in name
- "Build a report from data" → match assembly/documentation skills
Edge Cases
| Scenario | Handling |
|---|---|
| No matches above 60% threshold | Return empty recommendations[] with gaps listing unmet needs |
| Multiple skills with identical scores | Prefer more specific skill (higher specificity score) |
| Ambiguous user requirements | Set clarificationNeeded: true with targeted questions |
| Skill matches multiple requirements | Include once with highest-scoring requirement as primary |
| Installed vs available skills | Prefer installed skills when scores are within 10% |
Mission Writing Guidelines
Each mission should:
- Start with an action verb (Analyze, Extract, Generate, Create, Transform)
- Describe the specific goal for this step
- Mention key outputs expected
- Reference context from previous steps if applicable
- Be 2-4 sentences
Good mission example:
Deep analysis of video transcript. Extract key themes, important quotes with timestamps, and narrative structure. Focus on insights that would interest the user based on their profile.
Bad mission example:
Analyze the content.
Important Rules
- Skills-first - Never recommend agents, only skills
- Include missions - Every recommendation must have a detailed mission
- Score realistically - Don't inflate match scores
- Complete data flow - Ensure all dependencies are resolvable
- Flag gaps honestly - Report capabilities that can't be matched
- Include goalId - Each recommendation must have a
goalIdlinking it to a clarification goal
Clarifications Schema (v0.6.4)
When user requirements are ambiguous, include clarifying questions in the response. The wizard UI uses these to gather additional context before generating the final workflow.
Clarification Fields
| Field | Type | Description |
|---|---|---|
clarificationNeeded | boolean | Whether clarifying questions should be shown |
clarifications.sections | Section[] | Tab-based sections for wizard navigation |
Section Schema
{
"id": "goals",
"title": "Goals",
"completed": false,
"questions": [...]
}
Question Schema
{
"id": "primary-goal",
"text": "What are the primary goals for this workflow?",
"type": "single-select | multi-select | text",
"options": [
{ "id": "analyze", "label": "Analyze and extract key insights", "inferred": true }
],
"reason": "Optional explanation for why this was inferred"
}
Question Types
| Type | Description | Use Case |
|---|---|---|
single-select | One option only (●/○) | Content type, depth level |
multi-select | Multiple options (✓/☐) | Goals, features to include |
text | Free-form input | Custom names, descriptions |
Inferred Values
Set inferred: true on options that match keywords in the user's description:
- "video" or "youtube" → infer video content type
- "analyze" → infer analyze goal
- "summar" → infer summarize goal
- "generat" or "creat" → infer generate goal
Recommendation goalId
Each recommendation must include a goalId that links to a goal option:
{
"skill": "media-reviewer",
"suggestedStepId": "analyze-content",
"goalId": "analyze",
"matchScore": 0.92
}
This allows the wizard to filter recommendations based on selected goals in real-time.
Structured Preferences for Enriched Prompt (v0.6.4)
When wizard answers are included in the enriched prompt (via "User clarifications: Q: ... A: ..."), these become structured preferences that MUST be incorporated into the workflow.
Common Preference Types
| Preference Category | Example Questions | How to Use |
|---|---|---|
| PLATFORMS | "Which social media platforms?" | Inject into social/output step missions |
| ARTICLE_COUNT | "How many articles/items?" | Inject into search/filter step missions |
| FOCUS_AREAS | "Which topics/areas to focus on?" | Inject into search and analysis missions |
| OUTPUT_FORMAT | "What format should output be?" | Inject into final output step mission |
| DEPTH | "How deep should analysis be?" | Adjust analysis step detail level |
Preference Extraction from Enriched Prompt
When receiving an enriched prompt like:
User clarifications: Q: Which platforms? A: twitter, linkedin. Q: How many articles? A: top5. Q: Focus areas? A: llm, adoption.
Extract as structured data:
PLATFORMS: twitter, linkedin
ARTICLE_COUNT: 5
FOCUS_AREAS: llm, adoption
Mission Templates with Preferences
WITHOUT preferences (BAD):
Search for AI news articles.
WITH preferences (GOOD):
Search for top 5 AI news articles focusing on LLM developments and adoption trends.
WITHOUT preferences (BAD):
Compile findings into a report.
WITH preferences (GOOD):
Create engaging social media posts optimized for twitter and linkedin, focusing on LLM and adoption angles.
Workflow Executor Skill (v0.6.9)
Execute looplia workflows defined in workflows/*.md files using the skills-first architecture.
When to Use
Use this skill when:
- Handling
/runcommands - Executing workflow-as-markdown definitions
- Orchestrating multi-step skill workflows
⚠️ CRITICAL EXECUTION MODEL - READ FIRST
YOU (the model reading this skill) must execute the step loop directly. DO NOT delegate.
┌─────────────────────────────────────────────────────────────────────┐
│ YOU (main agent) iterate through steps, making ONE Task call each │
│ │
│ FOR step IN workflow.steps: │
│ 1. Call Task(general-purpose) for THIS STEP ONLY │
│ 2. WAIT for Task to complete │
│ 3. Validate output │
│ 4. THEN move to next step │
│ │
│ ❌ WRONG: Task("Execute all workflow steps...") │
│ ✅ RIGHT: Task("Execute step: summary"), Task("Execute step: ideas")│
└─────────────────────────────────────────────────────────────────────┘
3 steps = 3 Task calls. You MUST make 3 separate Task tool invocations.
CRITICAL: Task Invocation with general-purpose Subagent
v0.6.9: Using built-in general-purpose subagent for ALL workflow steps (all providers).
When executing a step with skill: {name} and mission::
{
"subagent_type": "general-purpose",
"description": "Execute step: {step.id}",
"prompt": "Execute skill '{step.skill}' for step '{step.id}'.\n\n## Mission\n{step.mission}\n\n## Execution Protocol\n1. Read input files (if provided)\n2. Invoke the skill using Skill tool\n3. Execute the mission with skill context\n4. Write JSON output to the specified path using Write tool\n\n## CRITICAL: Output Writing is MANDATORY\nYOU MUST CALL THE WRITE TOOL before completing. If you don't write the file, the workflow fails.\n\n## Rules\n- ALWAYS invoke the specified skill using Skill tool\n- ALWAYS write output to the exact path using Write tool\n- NEVER return results as text - always write JSON to output file\n- NEVER spawn Task subagents - execute skills directly\n- ALWAYS include contentId in JSON outputs\n\nInput: {resolved input path}\nOutput: {step.output}\nValidation: {step.validate JSON}"
}
Example:
- id: analyze-content
skill: media-reviewer
mission: |
Deep analysis of video transcript. Extract key themes,
important quotes, and narrative structure.
input: ${{ sandbox }}/inputs/content.md
output: ${{ sandbox }}/outputs/analysis.json
Task tool call:
{
"subagent_type": "general-purpose",
"description": "Execute step: analyze-content",
"prompt": "Execute skill 'media-reviewer' for step 'analyze-content'.\n\n## Mission\nDeep analysis of video transcript. Extract key themes, important quotes, and narrative structure.\n\n## Execution Protocol\n1. Read input files (if provided)\n2. Invoke the skill using Skill tool\n3. Execute the mission with skill context\n4. Write JSON output to the specified path using Write tool\n\n## CRITICAL: Output Writing is MANDATORY\nYOU MUST CALL THE WRITE TOOL before completing. If you don't write the file, the workflow fails.\n\n## Rules\n- ALWAYS invoke the specified skill using Skill tool\n- ALWAYS write output to the exact path using Write tool\n- NEVER return results as text - always write JSON to output file\n- NEVER spawn Task subagents - execute skills directly\n- ALWAYS include contentId in JSON outputs\n\nInput: sandbox/video-2025-01-15-abc123/inputs/content.md\nOutput: sandbox/video-2025-01-15-abc123/outputs/analysis.json\nValidation: {\"required_fields\":[\"contentId\",\"headline\",\"keyThemes\"]}"
}
Rules
- ALWAYS use
subagent_type: "general-purpose"for ALL workflow steps - NEVER use custom subagent_type per step (removed in v0.6.1)
- VALIDATE that step has both
skill:andmission:fields - REJECT steps using deprecated
run:syntax
Why Per-Step Task Calls (Context Isolation)
Each Task(general-purpose) creates a separate context window:
- Isolates step processing from main agent context
- Prevents context pollution across steps
- Enables focused execution with only relevant inputs
NEVER batch multiple steps - this defeats context isolation.
Anti-Patterns (VIOLATIONS = TEST FAILURE)
❌ FATAL ERROR - Delegating entire workflow to one Task:
{
"description": "Execute workflow: writing-kit",
"prompt": "Run all workflow steps..."
}
This is WRONG. You made 1 Task call. Tests expect 3. TEST WILL FAIL.
❌ FATAL ERROR - Executing skills inline without Task:
Skill("media-reviewer") // NO! You must use Task wrapper
Skill("idea-synthesis") // NO! You must use Task wrapper
This is WRONG. Each step MUST be wrapped in a Task call.
✅ CORRECT - One Task call per step (3 steps = 3 Task calls):
Task("Execute step: summary") // Task #1
→ Subagent invokes Skill("media-reviewer")
Task("Execute step: ideas") // Task #2
→ Subagent invokes Skill("idea-synthesis")
Task("Execute step: writing-kit") // Task #3
→ Subagent invokes Skill("writing-kit-assembler")
Verification: Count your Task tool calls. If workflow has 3 steps, you MUST have 3 Task calls.
Step Field Validation (v0.6.3)
Before executing a step, validate:
| Field | Required | Error if Missing |
|---|---|---|
skill | Yes | "Step '{id}' missing required 'skill' field" |
mission | Yes | "Step '{id}' missing required 'mission' field" |
input | Conditional | Required unless skill is input-less capable (e.g., search) |
output | Yes | "Step '{id}' missing required 'output' field" |
run | FORBIDDEN | "Step '{id}' uses deprecated 'run:' syntax. Migrate to 'skill:' + 'mission:'" |
Input-less Capable Skills
These skills can operate without an input field:
browser-research- Executes research missions autonomously (from looplia-skills)
Example input-less step:
- id: find-news
skill: browser-research
mission: |
Search Hacker News for today's top 3 AI stories.
Extract title, URL, points, and brief summary.
output: ${{ sandbox }}/outputs/news.json
# No input field - browser-research operates autonomously
Execution Protocol
Phase 1: Sandbox Setup
New Sandbox with Named Inputs (v0.6.3 - when --input provided):
-
Generate sandbox ID:
{first-input-name}-{YYYY-MM-DD}-{random4chars} Example: video-transcript-2025-12-18-xk7m -
Create folder structure:
sandbox/{sandbox-id}/ ├── inputs/ │ ├── video-transcript.md # Named input files │ └── user-notes.md ├── outputs/ # Step outputs go here ├── logs/ # Session logs └── validation.json # Validation state -
Copy each input file to
inputs/{name}.md
New Sandbox with Single File (legacy - when --file provided):
-
Generate sandbox ID:
{content-slug}-{YYYY-MM-DD}-{random4chars} Example: my-article-2025-12-18-xk7m -
Create folder structure and copy to
inputs/content.md
Input-less Sandbox (v0.6.3 - no inputs required):
For workflows using only input-less capable skills (e.g., search):
-
Generate sandbox ID from workflow name:
{workflow-slug}-{YYYY-MM-DD}-{random4chars} Example: hn-reporter-2025-12-18-xk7m -
Create folder structure with empty
inputs/directory
Resume Sandbox (when --sandbox-id provided):
- Verify sandbox exists
- Load
validation.jsonto see completed steps - Continue from first incomplete step
Phase 2: Workflow Parsing
-
Read workflow file:
workflows/{workflow-id}.md -
Parse YAML frontmatter:
name: workflow-name version: 1.0.0 description: ... steps: - id: step-one skill: skill-name mission: | Task description... input: ... output: ... -
Validate each step has
skill:andmission:(rejectrun:) -
Build dependency graph from
needs:fields
Phase 3: Validation State
Generate validation.json (new sandbox):
{
"workflow": "writing-kit",
"version": "2.0.0",
"sandboxId": "article-2025-12-18-xk7m",
"createdAt": "2025-12-18T10:30:00Z",
"steps": {
"analyze-content": {
"output": "outputs/analysis.json",
"validated": false
},
"generate-ideas": {
"output": "outputs/ideas.json",
"validated": false
},
"build-writing-kit": {
"output": "outputs/writing-kit.json",
"validated": false
}
}
}
Phase 4: Dependency Resolution
Compute execution order using topological sort:
Input:
analyze-content: { needs: [] }
generate-ideas: { needs: [analyze-content] }
build-writing-kit: { needs: [analyze-content, generate-ideas] }
Computed order: [analyze-content, generate-ideas, build-writing-kit]
Phase 5: Step Execution Loop (YOU MUST DO THIS)
YOU execute this loop. DO NOT delegate the loop to a subagent.
YOU (main agent) must:
┌────────────────────────────────────────────────────────────────┐
│ for (const step of steps) { │
│ // 1. YOU call Task tool │
│ await Task({ │
│ subagent_type: "general-purpose", │
│ description: `Execute step: ${step.id}`, │
│ prompt: `Execute skill '${step.skill}' for step...` │
│ }); │
│ │
│ // 2. YOU wait for Task to complete │
│ // 3. YOU validate output │
│ // 4. YOU update validation.json │
│ // 5. YOU move to next step │
│ } │
└────────────────────────────────────────────────────────────────┘
Execution checklist:
- Get first unvalidated step from dependency order
- YOU make ONE
Task(general-purpose)call for THIS step only - YOU WAIT for Task completion before proceeding
- YOU validate output, update validation.json
- YOU REPEAT for next unvalidated step
- YOU STOP when ALL steps are validated
MANDATORY: 3 steps = 3 Task calls. Count them. If you made fewer, you did it wrong.
FOR EACH step in dependency order:
│
▼
┌─────────────────────────────────────────┐
│ Check: output exists AND validated? │
└────────────────┬────────────────────────┘
│
┌───────┴───────┐
│ │
▼ YES ▼ NO
┌─────────┐ ┌─────────────────────────────┐
│ SKIP │ │ 1. INVOKE Task tool: │
│ (done) │ │ subagent_type: │
└─────────┘ │ "general-purpose" │
│ │
│ 2. Subagent invokes the │
│ specified skill │
│ │
│ 3. VALIDATE output │
│ │
│ 4. UPDATE validation.json │
│ │
│ 5. IF FAILED: retry (max 2x) │
└─────────────────────────────┘
Phase 6: Task Tool Invocation
For step:
- id: analyze-content
skill: media-reviewer
mission: |
Deep analysis of video transcript. Extract key themes,
important quotes with timestamps, and narrative structure.
input: ${{ sandbox }}/inputs/content.md
output: ${{ sandbox }}/outputs/analysis.json
validate:
required_fields: [contentId, headline, keyThemes]
Invoke Task tool:
{
"subagent_type": "general-purpose",
"description": "Execute step: analyze-content",
"prompt": "Execute skill 'media-reviewer' for step 'analyze-content'.\n\n## Mission\nDeep analysis of video transcript. Extract key themes, important quotes with timestamps, and narrative structure.\n\n## Execution Protocol\n1. Read input files (if provided)\n2. Invoke the skill using Skill tool\n3. Execute the mission with skill context\n4. Write JSON output to the specified path using Write tool\n\n## CRITICAL: Output Writing is MANDATORY\nYOU MUST CALL THE WRITE TOOL before completing.\n\n## Rules\n- ALWAYS invoke the specified skill using Skill tool\n- ALWAYS write output to the exact path using Write tool\n- NEVER return results as text - always write JSON to output file\n- ALWAYS include contentId in JSON outputs\n\nInput: sandbox/article-2025-12-18-xk7m/inputs/content.md\nOutput: sandbox/article-2025-12-18-xk7m/outputs/analysis.json\nValidation: {\"required_fields\":[\"contentId\",\"headline\",\"keyThemes\"]}"
}
Phase 7: Validation
After step output is written:
-
Use workflow-validator skill
-
Run validation script:
bun .claude/skills/workflow-validator/scripts/validate.ts \ sandbox/{id}/outputs/analysis.json \ '{"required_fields":["contentId","headline","keyThemes"]}' -
Parse result:
{ "passed": true, "checks": [ { "name": "has_contentId", "passed": true } ] } -
If passed: Update
validation.jsonwithvalidated: true -
If failed: Retry step with feedback (max 2 retries)
Phase 8: Return Final Output
When step with final: true passes validation:
- Read final artifact from
sandbox/{id}/outputs/{artifact} - Return structured result:
{ "status": "success", "sandboxId": "article-2025-12-18-xk7m", "workflow": "writing-kit", "artifact": { ... } }
Variable Substitution (v0.6.9)
Resolve variables before passing to general-purpose subagent:
| Variable | Resolution | Example |
|---|---|---|
${{ sandbox }} | sandbox/{sandbox-id} | sandbox/article-2025-12-18-xk7m |
${{ inputs.{name} }} | sandbox/{id}/inputs/{name}.md | sandbox/.../inputs/video1.md |
${{ steps.{id}.output }} | Output path of step {id} | sandbox/.../outputs/analysis.json |
Named Inputs (v0.6.3)
Workflows can declare named inputs in their frontmatter:
inputs:
- name: video-transcript
required: true
description: The video transcript to analyze
- name: user-notes
required: false
description: Optional user notes
Steps reference inputs via ${{ inputs.name }}:
steps:
- id: analyze
skill: media-reviewer
mission: Analyze the video content
input: ${{ inputs.video-transcript }}
output: ${{ sandbox }}/outputs/analysis.json
CLI provides inputs via --input:
looplia run writing-kit --input video-transcript=video.md --input user-notes=notes.md
Step Output References
input: ${{ steps.analyze-content.output }}
# Resolves to: sandbox/article-2025-12-18-xk7m/outputs/analysis.json
Error Handling
| Scenario | Action |
|---|---|
| Workflow not found | Error with available workflows |
Step uses run: syntax | Error: "Migrate to skill: + mission: syntax" |
Step missing skill: | Error: "Step missing required 'skill' field" |
Step missing mission: | Error: "Step missing required 'mission' field" |
| Sandbox not found | Error with suggestion to use --file |
| Step fails | Retry up to 2 times with feedback |
| Validation fails | Provide specific failed checks to skill-executor |
| Max retries exceeded | Report failure with details |
Example Execution Trace
/run writing-kit --file article.md
1. [SANDBOX] Created: sandbox/article-2025-12-18-xk7m/
- inputs/content.md (copied)
- validation.json (generated)
2. [WORKFLOW] Loaded: workflows/writing-kit.md
- version: 2.0.0
- steps: [analyze-content, generate-ideas, build-writing-kit]
3. [VALIDATE] Schema check passed
- All steps have skill: field ✓
- All steps have mission: field ✓
- No deprecated run: syntax ✓
4. [ORDER] Computed: [analyze-content, generate-ideas, build-writing-kit]
5. [STEP] analyze-content
- Task tool: subagent_type="general-purpose"
- Skill: media-reviewer
- Output: outputs/analysis.json
- Validate: PASSED
- Update: validation.json (analyze-content.validated = true)
6. [STEP] generate-ideas
- Task tool: subagent_type="general-purpose"
- Skill: idea-synthesis
- Output: outputs/ideas.json
- Validate: PASSED
- Update: validation.json (generate-ideas.validated = true)
7. [STEP] build-writing-kit
- Task tool: subagent_type="general-purpose"
- Skill: writing-kit-assembler
- Output: outputs/writing-kit.json
- Validate: PASSED
- Update: validation.json (build-writing-kit.validated = true)
8. [COMPLETE] Final output: writing-kit.json
File References
- Workflow definitions:
workflows/*.md - Subagent: Built-in
general-purposeagent (v0.6.9) - Skill definitions:
plugins/*/skills/*/SKILL.md - Sandbox storage:
sandbox/{sandbox-id}/ - Validator script:
.claude/skills/workflow-validator/scripts/validate.ts
Workflow Schema Composer
Generate complete, valid workflow definitions from skill recommendations.
Purpose
Transform the output from skill-capability-matcher into a ready-to-use looplia workflow markdown file that follows the v0.6.2 schema.
Process
Step 1: Receive Inputs
From skill-capability-matcher output:
- Skill sequence with step IDs
- Mission descriptions for each step
- Data flow dependencies
- Original user requirements
- Explicit name (if
--nameflag was provided) - use this exact name for the workflow
Step 1.5: Parse User Preferences from Enriched Prompt (v0.6.4)
CRITICAL: User preferences from wizard answers MUST be incorporated into step missions.
When the enriched prompt contains "User clarifications: Q: ... A: ..." sections, extract each preference:
Example enriched prompt:
/build search hackernews for AI news. User clarifications: Q: Which social media platforms? A: twitter, linkedin. Q: How many articles? A: top5. Q: Focus areas? A: llm, adoption. Q: Output format? A: posts
Extract as structured preferences:
| Question Pattern | Preference Key | Value | Inject Into |
|---|---|---|---|
| "platforms" / "social media" | PLATFORMS | twitter, linkedin | Output/social step mission |
| "how many" / "articles" / "count" | COUNT | 5 | Search/filter step mission |
| "focus" / "areas" / "topics" | FOCUS | llm, adoption | Search and analysis missions |
| "format" / "output" / "include" | FORMAT | posts | Final output step mission |
Preference Injection Rules:
- COUNT preferences → Add to search/fetch step: "Find top 5 articles..."
- FOCUS preferences → Add to search and analysis: "...focusing on LLM and adoption trends"
- PLATFORM preferences → Add to output step: "...optimized for twitter and linkedin"
- FORMAT preferences → Add to output step: "Create posts (not reports)..."
Step 2: Design Steps
For each recommended skill:
- id: {suggestedStepId}
skill: {skill-name}
mission: |
{mission description from matcher}
needs: [{dependencies}]
input: {input path(s)}
output: {output path}
model: {optional model override}
validate:
required_fields: [{fields}]
Step 3: Resolve Dependencies
Use dataFlow from matcher:
- Steps with no dependencies:
needs:is omitted - Dependent steps: list all required step IDs in
needs: - Final step: add
final: true
Step 4: Design Input/Output Paths
Use variable substitution:
${{ sandbox }}/inputs/content.md- Initial input (for workflows requiring input)${{ sandbox }}/outputs/{step-id}.json- Step outputs${{ steps.{id}.output }}- Reference previous step output
Input-Less Capable Skills (v0.6.3)
These skills can operate WITHOUT an input field - they fetch/generate data autonomously:
| Skill | Capability |
|---|---|
search | Web search, API queries, autonomous data fetching |
When a workflow's first step uses an input-less capable skill:
- OMIT the
input:field entirely from that step - The mission description drives the skill's behavior
- Subsequent steps reference the output:
${{ steps.{id}.output }}
Example input-less first step:
- id: fetch-data
skill: browser-research
mission: |
Search the web for recent technology trends.
Extract titles, URLs, and key details.
output: ${{ sandbox }}/outputs/data.json
# NO input field - browser-research operates autonomously
Step 5: Suggest Validation
Based on skill output type:
- Analysis skills:
required_fields: [contentId, headline, keyThemes] - Idea skills:
required_fields: [contentId, hooks, angles] - Assembly skills:
required_fields: [contentId, suggestedOutline]
Step 6: Compose Frontmatter (v0.7.0)
CRITICAL: If --name flag was provided, use that exact name. Do not derive or modify it.
---
name: {explicit-name OR derived-from-description}
version: 1.0.0
description: {user's original description, cleaned up}
# v0.7.0: Explicit skills declaration for selective plugin loading
skills:
- {skill-name-1}
- {skill-name-2}
- ...
steps:
- id: ...
---
Skills Declaration (v0.7.0):
Extract unique skill names from all step recommendations and list them in the skills: field.
This enables selective plugin loading at runtime - only required skills are loaded.
Naming rules:
- If
--name article-summarywas provided → usearticle-summaryexactly - If no
--name→ derive from description (e.g., "analyze videos" → "video-analyzer") - Always use kebab-case for names
- Always include
skills:field with all unique skills from steps
Step 7: Generate Markdown Body
Add usage documentation:
For workflows requiring input:
# {Workflow Name}
{Brief description}
## Usage
```bash
looplia run {workflow-name} --file <content.md>
**For input-less workflows (v0.6.3):**
```markdown
# {Workflow Name}
{Brief description}
## Usage
```bash
looplia run {workflow-name}
No input required - this workflow uses autonomous skills to fetch data.
**Steps section:**
```markdown
## Steps
1. **{step-id}**: {brief description}
2. ...
Output Format
Return a JSON object (v0.7.3: used by CLI for artifact persistence):
{
"filename": "video-to-blog.md",
"content": "---\nname: video-to-blog\nversion: 1.0.0\n...\n---\n\n# Video to Blog Workflow\n..."
}
Important: content MUST be the complete, ready-to-write markdown file including:
- Full YAML frontmatter (between
---delimiters) - Markdown body (usage docs, steps section)
The CLI writes this content directly to {workspace}/workflows/{filename}.
Schema Reference
See SCHEMA.md in this skill directory for the complete v0.6.2 workflow schema.
Validation Rules (v0.6.3)
skill:is REQUIRED - Every step must have a skillmission:is REQUIRED - Every step must have a missionrun:is FORBIDDEN - Never use the old agent syntax- Step IDs must be unique - No duplicates
- Dependencies must exist - All
needs:references must be valid - No circular dependencies - Validate topological ordering
- Respect explicit
--name- If provided, use that exact name for filename andname:field - Input-less steps (v0.6.3) - Steps using
searchskill may OMITinput:field entirely
Example Output
---
name: video-to-blog
version: 1.0.0
description: Analyze YouTube videos and create blog outlines
# v0.7.0: Explicit skills declaration for selective plugin loading
skills:
- media-reviewer
- idea-synthesis
- writing-kit-assembler
steps:
- id: analyze-content
skill: media-reviewer
mission: |
Deep analysis of video transcript. Extract key themes,
important quotes with timestamps, and narrative structure.
input: ${{ sandbox }}/inputs/content.md
output: ${{ sandbox }}/outputs/analysis.json
model: haiku
validate:
required_fields: [contentId, headline, keyThemes, importantQuotes]
- id: generate-ideas
skill: idea-synthesis
mission: |
Generate hooks, angles, and questions from the analysis.
Read user profile for personalization context.
needs: [analyze-content]
input: ${{ steps.analyze-content.output }}
output: ${{ sandbox }}/outputs/ideas.json
validate:
required_fields: [contentId, hooks, angles, questions]
- id: build-outline
skill: writing-kit-assembler
mission: |
Create structured blog outline with sections, key points,
and supporting quotes from analysis and ideas.
needs: [analyze-content, generate-ideas]
input:
- ${{ steps.analyze-content.output }}
- ${{ steps.generate-ideas.output }}
output: ${{ sandbox }}/outputs/outline.json
final: true
validate:
required_fields: [contentId, suggestedOutline]
---
# Video to Blog Workflow
Transform video content into structured blog outlines.
## Usage
```bash
looplia run video-to-blog --file <transcript.md>
Steps
- analyze-content: Deep analysis using media-reviewer skill
- generate-ideas: Idea synthesis with user personalization
- build-outline: Assemble outline using writing-kit-assembler skill
## Important Rules
1. **Always use skill: syntax** - Never use `run: agents/X`
2. **Always include mission** - Detailed task description
3. **Use valid YAML** - Proper indentation and quoting
4. **Include validation** - Add `validate:` with appropriate fields
5. **Mark final step** - Last step gets `final: true`
6. **Respect --name flag** - If `--name X` is provided, the workflow MUST be named `X` and saved as `X.md`
7. **Detect input-less workflows** - If first step uses `search` skill, OMIT input field
8. **Incorporate user preferences (v0.6.4)** - Extract preferences from "User clarifications" and inject into step missions. Each preference MUST appear in at least one mission.
9. **Include skills declaration (v0.7.0)** - Always add `skills:` field listing all unique skill names from steps. This enables selective plugin loading at runtime.
## Example: Input-Less Workflow (v0.6.3)
When the workflow fetches data autonomously (no user input needed):
```yaml
---
name: daily-news-digest
version: 1.0.0
description: Fetch trending news and compile a digest report
# v0.7.0: Explicit skills declaration
skills:
- browser-research
- content-documenter
steps:
- id: fetch-news
skill: browser-research
mission: |
Search the web for today's trending technology news.
Extract title, URL, source, and brief summary for each story.
output: ${{ sandbox }}/outputs/news.json
# NO input field - browser-research operates autonomously
validate:
required_fields: [query, mode, results]
- id: compile-digest
skill: content-documenter
mission: |
Compile the news into a formatted digest with categories and insights.
needs: [fetch-news]
input: ${{ steps.fetch-news.output }}
output: ${{ sandbox }}/outputs/digest.json
final: true
validate:
required_fields: [reportTitle, sections, summary]
---
# Daily News Digest
Fetches and compiles trending news into a digest.
## Usage
```bash
looplia run daily-news-digest
No input required - this workflow fetches data autonomously.
## Example: User Preference Injection (v0.6.4)
Given enriched prompt:
/build search hackernews for AI news. User clarifications: Q: Which platforms? A: twitter, linkedin. Q: How many? A: top5. Q: Focus areas? A: llm, adoption. Q: Output format? A: posts
**Extracted preferences:**
- PLATFORMS: twitter, linkedin
- COUNT: 5
- FOCUS: llm, adoption
- FORMAT: posts
**BAD workflow (ignores preferences):**
```yaml
- id: fetch-news
skill: browser-research
mission: |
Search HackerNews for AI news articles.
Extract titles and summaries.
- id: compile-output
skill: content-documenter
mission: |
Compile the news into a report.
GOOD workflow (incorporates preferences):
- id: fetch-news
skill: browser-research
mission: |
Search HackerNews for the top 5 AI news articles
focusing on LLM developments and adoption trends.
Extract titles, URLs, and key summaries.
- id: compile-output
skill: content-documenter
mission: |
Create engaging social media posts optimized for
twitter and linkedin. Focus on LLM and adoption angles.
Output as posts, not a formal report.
Workflow Validator Skill
Validates JSON artifacts against validation criteria using deterministic script execution.
Automatic Validation via Hook (v0.6.0)
As of v0.6.0, the PostToolUse:Write hook automatically calls this validation script whenever an artifact is written to sandbox/*/outputs/*.json.
You typically don't need to manually invoke this skill - the hook handles it.
When to Manually Use This Skill
Use this skill only in these scenarios:
- Retrying after validation failure - when the hook blocked a write and you need to debug
- Debugging validation issues - to see detailed check results
- Checking artifacts outside the normal workflow - for ad-hoc validation
- Pre-checking before write - to validate data before writing to sandbox
What This Skill Does
- Reads validation criteria from
sandbox/{id}/validation.json - Runs deterministic validation script (no LLM tokens consumed)
- Returns pass/fail status with detailed check results
- Enables workflow completion verification
Validation Process
Step 1: Read Validation Criteria
Read the validation manifest at sandbox/{id}/validation.json:
{
"workflow": "writing-kit",
"version": "1.0.0",
"sandboxId": "article-2025-12-18-xk7m",
"steps": {
"summary": {
"output": "outputs/summary.json",
"validate": {
"required_fields": ["contentId", "headline", "tldr", "keyThemes"],
"min_quotes": 3,
"min_key_points": 5
},
"validated": false
}
}
}
Step 2: Run Validation Script
Execute the validation script with artifact path and criteria:
bun scripts/validate.ts <artifact-path> '<criteria-json>'
Example:
bun scripts/validate.ts sandbox/podcast-2024-12-08-ai/outputs/summary.json '{"required_fields":["contentId","headline"],"min_quotes":3}'
Step 3: Parse Results
The script returns JSON with pass/fail and individual checks:
{
"passed": true,
"checks": [
{ "name": "has_contentId", "passed": true, "message": "OK" },
{ "name": "has_headline", "passed": true, "message": "OK" },
{ "name": "min_quotes", "passed": true, "message": "Found 5 quotes (min: 3)" }
]
}
Step 4: Handle Results
If validation passes:
- Update
validation.jsonto setvalidated: truefor this output - Continue to next workflow step
If validation fails:
- Review failed checks
- Either retry the subagent with feedback
- Or report the issue to the user
Validation Criteria Reference
required_fields
Array of field names that must exist in the artifact:
"required_fields": ["contentId", "headline", "tldr"]
min_quotes
Minimum number of items in importantQuotes array:
"min_quotes": 3
min_key_points
Minimum number of items in bullets or key points array:
"min_key_points": 5
min_outline_sections
Minimum number of outline sections:
"min_outline_sections": 4
has_hooks
Requires hooks array with at least one item:
"has_hooks": true
Output Format
The validation script returns:
{
"passed": boolean,
"checks": [
{
"name": "check_name",
"passed": boolean,
"message": "Human-readable result"
}
]
}
Important Rules
- Automatic validation via hook - Hook handles validation on write; manual use only for retry/debugging
- Script is deterministic - No LLM context consumed
- Update validation.json - Mark steps validated when passed (v0.6.0 uses
.stepsnot.outputs) - Retry on failure - Give subagent feedback on what failed
- Check dependencies - Ensure required steps are validated before dependent steps
- Use exact paths - Artifact paths are relative to workspace root
Script Location
The validation script is at:
.claude/skills/workflow-validator/scripts/validate.ts
Run with Bun for TypeScript execution:
bun .claude/skills/workflow-validator/scripts/validate.ts <artifact> '<criteria>'
Commands 4
Build Workflow
Create a new workflow-as-markdown file with the proper structure.
Usage
/build-workflow <name>
Arguments
| Argument | Description |
|---|---|
name | Name for the new workflow (e.g., "research-kit") |
Example
/build-workflow research-kit
Execution
-
Validate name
- Check name is valid (lowercase, hyphens allowed)
- Check
workflows/{name}.mddoesn't already exist
-
Gather requirements
- Ask user about workflow purpose
- Ask about expected outputs
- Ask about required agents
-
Generate workflow file
- Create
workflows/{name}.md - Include YAML frontmatter with:
- name, description
- outputs with artifacts, agents, dependencies
- validation criteria placeholders
- Include markdown body with instructions
- Create
-
Generate agent stubs (optional)
- Create
.claude/agents/{agent-name}.mdfor each agent - Include skills frontmatter
- Include task instructions
- Create
Template Structure
---
name: {name}
description: {user-provided description}
outputs:
first-step:
artifact: step1.json
agent: step1-agent
validate:
required_fields: [field1]
final-step:
artifact: final.json
agent: final-agent
requires: [first-step]
final: true
validate:
required_fields: [result]
---
# {Name} Workflow
{Custom instructions for this workflow}
## Context
{What this workflow is for}
## Expected Outputs
{Description of each output}
Output
Report success with:
- Path to created workflow file
- Paths to any created agent files
- Suggested next steps (customize, test with
/run)
Build Looplia Workflow
Create a looplia workflow definition from natural language using the skills-first architecture.
Usage
/build [--name <name>] [description]
Arguments
| Argument | Description |
|---|---|
description | (Optional) Natural language description of what the workflow should do |
--name <name> | (Optional) Explicit workflow filename. If provided, use this exact name |
Execution
Use three skills in sequence:
Skill("plugin-registry-scanner")→ Discover available skills from pluginsSkill("skill-capability-matcher")→ Match requirements to skillsSkill("workflow-schema-composer")→ Generate workflow file
Each skill's SKILL.md contains implementation details. See plugins/looplia-core/skills/ for full documentation.
Workflow
- Gather requirements (if no description provided, ask user)
- Call
Skill("plugin-registry-scanner") - Call
Skill("skill-capability-matcher")with registry + requirements - Call
Skill("workflow-schema-composer")with matched skills +--nameflag if provided - Save generated workflow to
~/.looplia/workflows/{name}.md - Report success with run command example
Examples
Interactive Mode
User: /build
Claude: What should this workflow do?
User: Analyze YouTube videos and create blog outlines
Claude: Created: ~/.looplia/workflows/video-to-blog.md (3 steps)
Run with: looplia run video-to-blog --file <transcript.md>
Direct Mode
/build analyze videos and create blog outlines with key quotes
With Explicit Name
/build --name article-summary summarize articles and extract key points
Error Handling
| Scenario | Response |
|---|---|
| No plugins installed | Error: "No skills found. Install looplia-writer plugin." |
| No matching skills | Warning: Show capability gaps, offer partial workflow |
| Invalid workflow generated | Retry generation with schema reminder |
List Workflows
Show all available workflows in the workflows/ directory.
Usage
/list-workflows
Execution
-
Scan workflows directory
- Read all
*.mdfiles inworkflows/ - Parse YAML frontmatter from each
- Read all
-
Extract metadata
- name
- description
- outputs (list of step names)
- final output name
-
Display results
- Table format with workflow info
- Show example usage
Example Output
Available Workflows
===================
| Workflow | Description | Steps |
|--------------|------------------------------|--------------------------------|
| writing-kit | Generate content writing kit | summary → ideas → writing-kit |
Usage:
/run writing-kit --file <path>
No Workflows Found
If no workflows exist:
- Report that no workflows are available
- Suggest using
/build-workflowto create one - Provide example:
/build-workflow my-workflow
Related Commands
/run <workflow-id> --file <path>- Execute a workflow/build-workflow <name>- Create a new workflow
Execute Looplia Workflow
Run a looplia workflow from workflows/ on provided content.
Usage
/run <workflow-id> --file <path>
/run <workflow-id> --sandbox-id <id>
Arguments
| Argument | Description |
|---|---|
workflow-id | Name of workflow (e.g., "writing-kit") |
--file <path> | Path to content file (creates new sandbox) |
--sandbox-id <id> | Resume existing sandbox |
Examples
/run writing-kit --file ~/articles/draft.md
/run writing-kit --sandbox-id draft-2025-12-18-abc123
Execution
Use the Skill("workflow-executor") to handle all execution.
The workflow-executor skill:
- Parses workflow YAML from
workflows/{workflow-id}.md - Creates/resumes sandbox
- Executes each step via
Task(skill-executor) - Manages validation state
- Returns final artifact
See plugins/looplia-core/skills/workflow-executor/SKILL.md for implementation details.
Error Handling
| Error | Action |
|---|---|
| Workflow not found | Report available workflows via /list-workflows |
| File not found | Report specific error with path |
| Sandbox not found | Report available sandboxes |
Sponsors
Details
- Marketplace
- memorysaver/looplia-core
- Source
- plugins/looplia-core
- Category
- Development