Home/AI Guide

AI-Assisted Skill Creation Guide

How to use AI at every stage of the Skill Factory pipeline — from intent decomposition to capability resolution to role-based skill generation.

How the AI Pipeline Works

Skill Factory uses two AI-facing specifications (SKILL.md files) as system prompts for Claude or any compatible LLM. These are not traditional code — they are structured instructions that tell the AI exactly how to behave at each stage.

Intent (natural language)
  │
  ▼
┌─────────────────────┐     ┌──────────────────────┐
│  Workflow Architect  │────▶│  Abstract DAG         │
│  (AI + SKILL.md)    │     │  (workflow.yaml)      │
└─────────────────────┘     │  nodes: "unresolved"  │
                            └──────────┬───────────┘
                                       │
                                       ▼
┌─────────────────────┐     ┌──────────────────────┐
│ Integration Resolver │────▶│  Resolved DAG         │
│  (AI + SKILL.md)    │     │  (workflow.yaml)      │
└─────────────────────┘     │  nodes: bound to IDs  │
       │                    │  + auth_manifest      │
       │                    │  + resolution_log     │
       ▼                    └──────────┬───────────┘
  Registry                             │
  (search, match,                      ▼
   register, depends)       ┌──────────────────────┐
                            │  Workflow Validator   │
                            │  (schema + structure) │
                            └──────────────────────┘

1. Creating Skills with AI (Workflow Architect)

What it does

The Workflow Architect takes a natural-language intent and decomposes it into an abstract workflow DAG. It does NOT choose implementations — it designs the structural blueprint.

How to use it

Write your intent

Describe the multi-step task you want to automate in plain English. Be specific about the goal, constraints, and success criteria. Example: "Create a blog post from a brief, generate a header image, publish to the CMS, and share on social media."

Send to the Builder Studio

Navigate to /studio/new and paste your intent. The UI sends it to the Workflow Architect AI along with the SKILL.md system prompt.

Review the generated DAG

The Architect produces a workflow.yaml with: nodes (abstract steps), edges (data flow), parallel groups, error strategy, and all capabilities set to "unresolved".

Edit if needed

You can modify the YAML directly — add nodes, change types, adjust parallelism. The schema is documented below.

API endpoint

# The Architect SKILL.md (system prompt for the AI)
GET /skills/architect

# After the AI generates workflow YAML, validate it:
POST /validate
{
  "workflow_yaml": "<the generated YAML string>"
}

Key constraints

All nodes must have capability: "unresolved"
The Architect does not bind capabilities (that is the Resolver's job)
3-12 nodes is typical; more than 15 suggests sub-workflows
Node IDs must be kebab-case and descriptive
Every node must declare inputs, outputs, and effects

2. Resolving Capabilities with AI (Integration Resolver)

What it does

The Integration Resolver takes the abstract DAG and binds each node to a concrete capability from the registry. It has three strategies for handling gaps.

Resolution strategies

A: Direct Match

Registry has an existing capability that matches the node's I/O signature.

match(inputs={"prompt": "string"}, outputs={"image_url": "media.image"}) → api:openai-dall-e

B: Skill Acquisition

No match exists, but the capability is narrow and well-defined. The AI builds a new skill and registers it.

generate-social-copy → built and registered as skill:generate-social-copy

C: Recursive Decomposition

The gap is itself a multi-step workflow. The Architect designs a sub-workflow, the Resolver resolves it recursively (max depth 3).

share-on-social → decomposed into composite:multi-platform-share

D: Unresolvable

The capability requires external tooling that cannot be built or decomposed. Flagged for manual resolution.

publish-to-cms → capability: "unresolvable" (requires specific CMS integration)

Candidate ranking

Priority	Criterion	Prefer	Over
1	Capability type	skill	api > interaction > building new
2	Type match	Exact match on all ports	Compatible types, partial match
3	Effect count	Fewer effects	More effects
4	Status	active	experimental > deprecated
5	Specificity	Purpose-specific	Generic
6	Dependency count	Fewer depends_on	More depends_on

API endpoints used during resolution

# Get the Resolver SKILL.md (system prompt for the AI)
GET /skills/resolver

# Search registry by description
GET /registry/search?q=image+generation

# Match by I/O type signature
POST /registry/match
{
  "inputs": {"prompt": "string"},
  "outputs": {"image_url": "media.image"}
}

# Resolve a capability's full entry
GET /registry/{capability_id}

# Register a newly built capability
POST /registry/register
{
  "entry": { "id": "skill:generate-social-copy", ... }
}

# Check transitive dependency tree
GET /registry/{capability_id}/depends

3. Comparing Skills and Capabilities

When you need to compare

During resolution, the AI ranks multiple candidate capabilities. You can also compare manually using the registry API.

Compare by I/O signature

# Find all capabilities that accept a text prompt and produce an image
POST /registry/match
{
  "inputs": {"prompt": "string"},
  "outputs": {"image_url": "media.image"}
}

# Returns candidates like:
# - skill:generate-image (skill, effects: [none])
# - api:openai-dall-e (api, effects: [network, cost])
# - interaction:midjourney-browser (interaction, effects: [network, cost, auth_required])

Compare by text search

# Search by name, tags, or description
GET /registry/search?q=image+generation

# Search for all writing-related capabilities
GET /registry/search?q=writing

# Get full details of a specific capability for comparison
GET /registry/skill:write-blog-post

Compare dependency trees

# Compare complexity by checking dependency chains
GET /registry/skill:write-blog-post/depends
# → ["skill:write-blog-post"]  (simple, no dependencies)

GET /registry/composite:social-media-campaign/depends
# → ["skill:write-blog-post", "api:openai-dall-e", ..., "composite:social-media-campaign"]
#   (complex, multiple transitive dependencies)

4. Generating Skills from Roles (O*NET)

What it does

The O*NET parser transforms occupational data into factory-compatible input. This lets you seed the marketplace with role-based skill templates — e.g., "automate everything a PR Specialist does."

Step-by-step workflow

Parse O*NET occupation data

Upload or paste a role YAML file (e.g., 27-3031.00 — Public Relations Specialist). The parser extracts the role metadata, tasks, and connected tools.

Extract automatable tasks

The parser filters tasks by automatable status (fully or partially). Each task gets annotated with a capability_type derived from its tools (e.g., "writing" → skill, "social_media_api" → api).

Generate factory input

Produces a complete factory-compatible YAML with: role metadata, annotated tasks, connected tools in registry format, and suggested capability stubs.

Feed to the Architect

Take the suggested capabilities and feed them to the Workflow Architect as intents. The Architect designs workflows for each automatable task cluster.

Resolve and publish

The Integration Resolver binds nodes, the Validator checks the result, and you publish the role-based agents to the marketplace.

API endpoints

# Parse an O*NET occupation YAML
POST /onet/parse
{
  "yaml_content": "<raw YAML string>"
}
# Returns: factory_input with role metadata, tasks, tools, suggested capabilities

# Extract automatable tasks only
POST /onet/automatable-tasks
{
  "role_data": { "tasks": [...], ... },
  "fully_only": false
}
# Returns: annotated tasks with capability_type

Tool-to-capability mapping

Tool	Capability Type
`social_media_api, email, cms, survey_tools`	api
`writing, image_generation, document_generation`	skill
`document_analysis, data_analysis, web_research`	skill
`scheduling, project_management`	interaction

5. Validating Workflows

What the validator checks

Schema conformance against schemas/workflow.yaml
Required fields: name, version, inputs, outputs, nodes, edges
Edge references: all "from"/"to" targets reference valid nodes or workflow inputs
No duplicate edges
DAG acyclicity (cycle detection via 3-color DFS)
Node input connectivity (all required inputs wired via edges or defaults)

API endpoint

POST /validate
{
  "workflow_yaml": "<YAML string>"
}
# Returns: { valid: bool, errors: string[], warnings: string[] }

# Validate the registry itself
GET /registry/validate
# Returns: { valid: bool, errors: string[] }

6. Complete API Reference

All skill-factory operations are exposed via the FastAPI service at SKILL_FACTORY_URL (default: http://localhost:8000).

GET/healthService health check + registry size

POST/validateValidate a workflow YAML

GET/registry/search?q=Fuzzy search by name/tags/description

POST/registry/matchFind capabilities by I/O type signature

GET/registry/{id}Resolve a capability by ID

POST/registry/registerAdd or update a capability

GET/registry/{id}/dependsTransitive dependency tree

GET/registry/validateValidate the entire registry

GET/registry/allList all capabilities

POST/onet/parseParse O*NET occupation YAML

POST/onet/automatable-tasksExtract automatable tasks

GET/skills/architectArchitect SKILL.md (AI system prompt)

GET/skills/resolverResolver SKILL.md (AI system prompt)

GET/skills/validatorValidator SKILL.md (AI system prompt)

GET/schemas/workflowWorkflow YAML schema

GET/schemas/registryRegistry YAML schema

7. End-to-End Example: PR Specialist Automation

Here is a complete example showing how to use the AI pipeline to automate a Public Relations Specialist's tasks from O*NET data.

Step 1: Parse O*NET data

POST /onet/parse
{
  "yaml_content": "role:\n  onet_code: \"27-3031.00\"\n  title: \"Public Relations Specialist\"\n  ..."
}

# Returns factory_input with 6 automatable tasks:
# - draft_press_releases (skill)
# - create_media_kits (skill)
# - manage_social_media (api)
# - monitor_media_coverage (skill)
# - coordinate_events (interaction)
# - generate_reports (skill)

Step 2: Generate workflows from suggested capabilities

# Feed each task cluster as an intent to the Architect AI:
# System prompt: GET /skills/architect → content
# User prompt: "Automate: draft press releases for product launches,
#   including research, drafting, and distribution to media lists"

# The Architect produces a workflow.yaml with nodes:
# research-topic → draft-release → review-edit → distribute-to-media

Step 3: Resolve capabilities

# System prompt: GET /skills/resolver → content
# Input: the abstract workflow.yaml from Step 2
# The Resolver:
# 1. Searches registry: GET /registry/search?q=press+release
# 2. Matches I/O: POST /registry/match
# 3. Binds: research-topic → skill:web-research
# 4. Builds: draft-release → skill:draft-press-release (via Skill Acquisition)
# 5. Flags: distribute-to-media → "unresolvable" (needs media list integration)

Step 4: Validate and publish

# Validate the resolved workflow
POST /validate
{ "workflow_yaml": "<resolved YAML>" }

# If valid, publish as an agent to the marketplace
POST /api/v1/builder/agents
{
  "name": "PR Press Release Pipeline",
  "slug": "pr-press-release",
  "workflowYaml": "<resolved YAML>",
  "floorPriceCents": 10,
  "category": "PR"
}