plugins/handsonai/skills/build/SKILL.md
This skill should be used when the user has an approved Design Spec and wants to build platform artifacts for their AI workflow. It offers a build path choice, researches integration availability, generates platform-appropriate artifacts (prompts, skills, agents, configs), and writes them to the right locations for the user's platform. This is Step 4 (Build) of the AI Workflow Framework.
npx skillsauth add jamesgray-ai/handsonai-plugins buildInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Take an approved Design Spec and generate platform-appropriate artifacts: prompts, skills, agents, configs, and connectors.
Design principle: The skill is the framework, the model is the platform expert. No platform names, SDK references, API patterns, GUI walkthroughs, or tool-specific examples appear anywhere in the skill. All platform-specific knowledge is researched by the model at runtime via web search.
Role: You are an Agentic AI Architect. Your role is to build solutions that map business workflows to AI building blocks across all three layers — Intelligence (Model, Context, Memory, Project), Orchestration (Prompt, Skill, Agent), and Integration (MCP, API, SDK, CLI). You think in terms of system design, artifact generation, and platform-specific implementation.
Artifact generation begins only after the Design Spec has been approved in the Design phase.
Read the workflow's manifest (outputs/[workflow-name]/workflow.yaml) to locate the artifacts, then read the Design Spec from the path registered there (normally outputs/[workflow-name]/design-spec.md). If the user specifies a file path, use that. If no manifest exists but legacy flat files (outputs/[name]-design-spec.md) do, use the legacy paths and offer to migrate them into a workflow folder + manifest. Otherwise, look for the most recent Design Spec in outputs/.
Parse the frontmatter first. The spec opens with YAML frontmatter containing: workflow, requirements_file, spec_version, definition_type, mechanism, involvement, platform, platform_mode, packaging, and counts. Use these values to summarize the spec — no need to parse the body to get the headline numbers.
Also load the Workflow Requirements. The Design Spec references the Workflow Requirements via its requirements_file frontmatter field (or the Source section if frontmatter is absent). Verify that file exists before proceeding — if the path doesn't resolve, stop and tell the user exactly which file is missing and where the spec expected it, rather than building against a spec whose canonical source is gone. Read that file too — it contains the per-step requirements, Context Inventory, Acceptance Criteria, Example Scenarios, and Human Gates that the Design Spec deliberately does NOT restate. Build needs both files together.
Confirm you've loaded both by summarizing: workflow name, orchestration mechanism, involvement mode, packaging, counts (steps, skills, agents, integrations), and that the Workflow Requirements was loaded.
Spec version compatibility:
spec_version: 2.2 (current) → current format with workflow-folder paths and the Safety & Permissions section; proceed.spec_version: 2.1 → same structure minus Safety & Permissions and using legacy flat paths; proceed, and apply the safety defaults from Step 5's write-scope pre-flight in place of the missing section.spec_version: 2.0 → older format without layer grouping or Orchestrator Outline; proceed (Build's fallback derives the orchestrator from Workflow Requirements directly).spec_version → spec predates the current format. Inform the user: "This spec is in an older format. Some fields (Packaging, Build Output column, Skill/Agent IDs, Deployment Plan, Orchestrator Prompt Outline) may be missing. I can either (a) proceed with what's available and ask questions as needed, or (b) you can regenerate the spec by running the Design skill again."Offer two paths:
"How would you like to proceed?
- I'll build it — I generate all artifacts (skills, agents, prompts, configs) based on the approved spec.
- I'll build it myself — The spec is your deliverable. I'll provide a Construction Guide with build sequence and platform-specific format guidance instead of generating artifacts."
If the user chooses path 2:
[skill-name] available. Invoke it (e.g., /[skill-name]) and pass the spec below as your starting context."test skill (Step 5)."Based on the orchestration mechanism, present ONLY the steps relevant to the user's mechanism:
Before starting any mechanism path: Check the Data Readiness Summary. For items with state "Partial" or "No", resolve required actions first — these gate dependent steps. If resolution requires user action (e.g., exporting data, granting access), present the action list and wait for confirmation before proceeding.
Prompt mechanism:
Skill-Powered Prompt mechanism:
Agent mechanism:
After presenting the mechanism-specific build path, proceed to Step 3.5 to discover available creation tools before generating any artifacts.
Before generating artifacts, discover what creation tools are available in this session. Skills are an open standard — they live in platform-specific directories but follow the same SKILL.md format everywhere.
Extract building block types from the loaded Design Spec — list each type and count (e.g., "3 skills, 1 agent, 1 MCP server config").
Discover available creation skills using two tiers:
Tier 1 — System-level discovery. Check if the current environment provides a list of available skills (typically shown in system reminders, session context, or tool listings). If available, scan skill names and descriptions for any that indicate the ability to create, generate, scaffold, or build one of the needed building block types. Match semantically — look for descriptions containing phrases like "create a skill", "build an agent", "scaffold a plugin", "create hooks", "generate MCP servers", etc.
Match generators, not guidance skills. Only count a skill as a creation tool if it takes a finished spec and produces the artifact file(s) — it scaffolds, generates, writes, or builds the artifact. Exclude interactive guidance / elicitation / teaching skills — those whose purpose is to walk a human through deciding an artifact's configuration (e.g. descriptions about "agent frontmatter", "when-to-use description", "how to structure an agent/skill", "agent tools and examples"). The approved Design Spec already contains all 12 skill / 13 agent fields, so a guidance skill would only re-open settled decisions and add no value — Build generates those artifacts inline instead.
Apply this test to each candidate: "Does this skill WRITE the artifact from a finished spec, or does it ASK ME to decide the configuration? Only the former qualifies." When in doubt, treat it as guidance (exclude it) and generate inline.
Tier 2 — Filesystem discovery (fallback). If no system-level skill list is available, or if the list may be incomplete, scan the platform-appropriate skill directories for SKILL.md files. Read each file's YAML frontmatter (name and description fields) to identify creation-capable skills. Use the platform's skill directory:
| Platform | Skill Directories |
|----------|------------------|
| Claude Code | .claude/skills/ |
| Cursor | .cursor/skills/, .claude/skills/, .codex/skills/, .agents/skills/ |
| Codex CLI | .agents/skills/ |
| Gemini CLI | .gemini/skills/, .agents/skills/ |
| VS Code Copilot | .github/skills/, .agents/skills/ |
| Cowork / Claude.ai | System-managed (Tier 1 only) |
For the authoritative and up-to-date directory listing, read docs/agentic-building-blocks/skills/index.md (Platform Implementations table).
If neither tier finds any skills (e.g., ChatGPT web, Gemini app), state: "No creation skills detected in this environment — all building blocks will be generated inline." Then proceed.
Build a Creation Tools Map. For each building block type needed by the spec, record the matched creation skill (if any) or "Inline generation" as the fallback:
| Building Block Type | Count | Matched Creation Skill | Method | |---|---|---|---| | Skill | 3 | (matched skill name or "none") | Delegate / Inline | | Agent | 1 | (matched skill name or "none") | Delegate / Inline |
Present the map for confirmation. Show the user: "Here's how I plan to build each block type. For items with a matched creation skill, I'll delegate to that skill's full workflow. For items without, I'll generate inline using reference specifications. Does this look right?"
Wait for user confirmation before proceeding.
Before generating artifacts, resolve platform-specific format requirements and integration documentation so that artifact generation (Step 6) produces correctly formatted output on the first pass.
Caching note: The registry JSON is fetched once per session. If the Design phase already fetched it, use the cached copy.
Tier 1 — Platform Doc Resolution
Resolve the platform registry local-first (or use session cache): if this skill is installed as part of the handsonai plugin, read the local copy at ${CLAUDE_PLUGIN_ROOT}/registries/platform-registry.json; otherwise (standalone install) fetch the remote copy from
https://raw.githubusercontent.com/jamesgray-ai/handsonai/main/plugins/handsonai/registries/platform-registry.json
Look up the user's platform in the platforms section of the registry JSON.
Determine mode and language:
mode field (code or guided) for the matched platform.code mode: read the language field (e.g., markdown, python, yaml).guided mode: note that artifacts will be GUI workflow steps and configuration options rather than files.If platform not found: Fall back to model knowledge combined with web search to determine the platform's artifact format. Log a warning: "Platform not found in registry — using model knowledge and web search for format requirements."
For each building block needing an artifact, fetch the corresponding doc URL from the registry:
docs section (e.g., skills, agents, mcp, hooks, prompts).Extract artifact format requirements:
Pass format requirements forward. Store the resolved format requirements so Step 6 (Generate Platform Artifacts) can use them directly instead of re-researching.
Tier 2 — Integration Doc Resolver
For each integration listed in the Design Spec's "Integration Options" section, resolve platform-specific integration documentation:
Read integration-registries from the cached registry JSON. This section catalogs known sources for integration documentation (e.g., MCP registry, platform marketplaces, connector catalogs).
Search each cataloged source. For each integration needing research:
mcp-registry search), use it.WebFetch fallback for uncataloged sources. If the integration is not found in any cataloged source, or the cataloged source has no MCP tool available:
Fallback ladder (never hard-fail). Both tiers depend on network access — the registry fetch can fail and WebFetch/web search may be unavailable on some platforms. Degrade gracefully and tell the user what was degraded: session cache (registry already fetched this session, incl. by Design) → model knowledge → web search → best-effort note. If WebFetch isn't available, say so and use web search; if neither is available, generate from model knowledge and flag the artifact format as unverified so the user double-checks before relying on it. Never block Build because a fetch failed.
Present a summary of resolved platform format requirements and integration docs to the user before proceeding.
This is separate from Step 3.5's creation tool discovery — here you're checking for workflow skills that have already been built and should be incorporated, not for skills that create other skills.
Before generating artifacts:
Read the "Integration Options" section from the loaded Design Spec. This section already identifies each integration, its category (built-in, available with setup, possible with code, manual), and source URLs discovered during the Design phase.
Use the carried-forward URLs as starting points. The Design phase's Integration Discovery already answered "what's available?" — the focus here is "how do I connect it on the user's platform?"
For each integration listed in the spec:
Web search is used for platform availability research — verifying setup steps, finding platform-specific guides, and confirming compatibility. Discovery of integrations themselves is already done. If the environment doesn't support web search, instruct the user to switch to a tool that does.
Write-scope pre-flight (required). For every integration the workflow must write to — create drafts, apply labels, create database rows/pages, send messages, create events — verify the connector actually has write access before building against it. Connectors are often connected read-only. If a needed write scope is missing:
Least-privilege pre-flight (required). Read the spec's Safety & Permissions section (Layer 1) and enforce its mitigations during connector setup:
spec_version ≤ 2.1), apply these as defaults and tell the user what you assumed.Present the integration mapping and ask the user to confirm before generating artifacts. If any critical integration is manual-only, discuss implications for the orchestration mechanism (may need to downgrade or add human-in-the-loop steps).
If the Integration Options section is missing from the spec (older format), inform the user and offer two paths: (a) Run Integration Discovery now — research available integration approaches for each tool identified in the spec's Integration Options or Step-by-Step Decomposition tables, or (b) proceed with web-search-only research for each integration need as it arises during artifact generation.
Based on the platform and packaging decisions from Architecture Decisions. Resolve the items in the spec's Deferred to Build section now:
Use the spec's Step-by-Step Decomposition Build Output column (or Capability Domain Mapping Build Output column for goal-driven) as your generation checklist. Each row tells you exactly what to produce:
New skill: SN → generate the skill defined in the matching Skill Candidates entryUse existing: [name] → no generation needed; verify the skill exists and reference itNew agent: AN → generate the agent defined in the matching Agent Configuration entryInline prompt → Workflow Requirements Step N → fold this step's Goal/Inputs/Outputs/Rules from the Workflow Requirements into the main orchestrator promptMCP server: [name] → configure the connector using the Integration Options entryHuman (no artifact) → skip; no AI artifact for this stepHandled by orchestrator (goal-driven only; legacy synonym Handled by agent) → no separate artifact; the capability is covered by the orchestration logic (the primary loop's orchestrator skill / CLAUDE.md run section) or a sub-agent's instructionsApply the spec's Packaging decision to group the generated artifacts:
When mechanism is Prompt or Skill-Powered Prompt: read the spec's Orchestrator Prompt Outline section as the structural skeleton for the orchestrator prompt. The outline names which step invokes which skill, where PAUSE points sit, and what the user provides at each gate. Expand the outline into the full orchestrator prompt by pulling step content (Goal, Inputs, Outputs, Rules & Edge Cases) from the Workflow Requirements. If the section is absent (older spec or mechanism = Agent), fall back to deriving the orchestrator directly from Workflow Requirements Step Details + Human Gates.
When mechanism is Agent on a primary-loop platform (Claude Code/Cowork): the primary session is the orchestrator (see Design's "Who is the orchestrator?"). Generate the user-triggered entry point as an orchestrator skill — disable-model-invocation: true, no context: fork (it must dispatch sub-agents from the primary loop), invoked as /name. Do not emit a slash command for this: custom commands are merged into skills, and a same-named skill would silently shadow the command. Name the orchestrator skill with the workflow name; give component/worker artifacts (synthesizers, etc.) capability-specific names so the user-facing entry point never collides with a sub-skill. The orchestrator skill's body holds the run sequence (e.g., clarify → dispatch sub-agents → collect → synthesize → save → review) and ends with the run-logging step: if the workflow runs on-platform, the orchestrator appends one row to outputs/[workflow-name]/runs.md at the end of every run — date, input/trigger, result, edits-needed — creating the file with its header if absent (per the spec's Deployment Plan Run Logging requirement).
a. Resolve platform documentation from the registry. Use the platform doc URLs fetched in Platform Research (Step 3.6) from the registry's platforms section. These provide current, authoritative documentation for each building block's artifact format.
If playbook platform guides are available locally (e.g., docs/platforms/claude/index.md), use them as supplementary context — not as the primary source.
b. Verify currency (if needed). The registry provides current doc URLs maintained by the framework author. Use web search only if the fetched docs appear outdated or if the registry was unavailable in Step 3.6.
c. Follow the resolved artifact format specifications. For each building block in the spec, use the artifact format extracted during Platform Research (Step 3.6). If Platform Research did not resolve a format (registry unavailable, platform not found), fall back to:
references/skill-spec.mdreferences/agent-spec.mdThe
references/*-spec.mdfiles are point-in-time snapshots, not the source of truth. Platform schemas drift; prefer the registry/doc lookup from Step 3.6 and use these only as a last-resort fallback. If a snapshot and live docs disagree, the live docs win.
d. Apply code vs guided mode branching. Based on the platform's mode from the registry (determined in Step 3.6):
language (Python, TypeScript, markdown). This is the standard behavior — proceed with artifact generation as described below.e. Generate each building block. For each building block in the spec, follow the Creation Tools Map from Step 3.5:
Field-role mapping (platform-agnostic — do NOT hardcode concrete keys). Design collects 12 skill / 13 agent fields. Each plays one of four roles; place it by role, and resolve the concrete destination (frontmatter key name, body section) at runtime from the platform docs fetched in Step 3.6. Field names and frontmatter schemas change per platform and over time, so the framework owns only the role, never the literal key:
Identity / activation — Name, Description, Trigger Examples → the platform's identity + auto-invocation mechanism (e.g., a description/name field and example blocks — whatever the platform calls them).
Instruction body — Mission, Responsibilities, Decision Logic, Failure Modes, Output Format, Tone & Style, Constraints → the artifact's prose body/system prompt.
Wiring / config — Model, Tools, Skills, Memory Scope, Stateful? → mapped to whatever config fields the platform exposes (e.g., Stateful?/Memory Scope → the platform's memory/persistence option, by its current name).
Framework-internal only — ID, Purpose, Covers Steps/Domains, Depends On → used for sequencing and cross-references during Build; never emitted into the generated artifact.
If a creation skill was matched for this block type:
If no creation skill was matched (inline generation):
https://agentskills.io/specification, fallback to references/skill-spec.md). Generate the skill using the Skill Candidates entry — use the Name field as the directory name and the Description field verbatim in the SKILL.md frontmatter. Apply platform-specific extensions as documented for the target platform.references/agent-spec.md. For other platforms, fall back to web search. Generate the agent using the Agent Configuration entry — use the Name as the filename, the Description field verbatim in the agent file frontmatter (and include the Trigger Examples as <example> blocks in the description), and the Mission, Responsibilities, Output Format, Tone & Style, and Constraints fields as the agent's system prompt body.f. Generate artifacts. The skill provides the specs (what each building block should do, its inputs/outputs/instructions from the Design phase). The model provides the implementation (how to build it on the user's platform, using the verified specification and platform documentation as authoritative sources).
g. Place and deploy each artifact per the Deployment Plan. The Design Spec's Deployment Plan table specifies the target location and deployment steps for every artifact. For each generated artifact:
claude mcp add ...", "upload zip via plugin marketplace", "create new GPT and paste instructions").Confirm before mutating the user's real accounts. Before any action that creates or modifies data in the user's live accounts — creating a Notion database/page, a Gmail label/draft, a calendar event, a Slack post, etc. — state the exact action and target and get explicit confirmation first. Batch related confirmations into one prompt where possible. (These are outward-facing, hard-to-reverse actions; never perform them silently as a side effect of "building.")
Never overwrite existing local files. Before creating any local artifact — especially context files (Status: Exists in the Context Inventory) — check the filesystem. If the file already exists, read and reuse it; do not overwrite without explicit confirmation. (Context artifacts marked Needs Creation in the spec may already have been supplied by the user since Design.)
After completing Build, summarize what was generated, where each artifact was placed, and any remaining manual deployment steps. Update the workflow manifest (outputs/[workflow-name]/workflow.yaml): set current_step: 4, last_updated, and record the generated artifact locations under an artifacts.platform_artifacts list. Then tell the user: "To test the workflow, run the test skill (Step 5) (or say 'Test the workflow I built')."
Prompts, skills, agents, orchestration configs, and connector setups in whatever format is appropriate to the user's chosen platform. Generated by the model based on the Design Spec and Architecture Decisions. For code-mode platforms, these are source files; for guided-mode platforms, these are step-by-step GUI instruction documents. For building blocks with a matched creation skill (discovered at runtime in Step 3.5), artifacts are built by delegating to that skill's full workflow. For building blocks without a matched creation skill, artifacts are generated inline using the format resolved from the platform registry in Step 3.6 (falling back to references/skill-spec.md for skills, references/agent-spec.md for Claude Code agents, or web search for other platforms).
documentation
Write Standard Operating Procedure documentation for workflows and save as markdown files. Selects full or lightweight SOP template based on autonomy level (deterministic vs. guided/autonomous), then adapts for workflow type (Manual, Augmented, Automated). Use when the user asks to write an SOP, document a workflow, create procedure documentation, or capture how a workflow is executed. Triggers on "write an SOP", "document this workflow", "create operating instructions", "how is this workflow executed".
development
Guide structured testing of AI workflow artifacts, evaluate output quality, identify which building blocks need adjustment, and determine readiness for deployment. Use when the user has built workflow artifacts and needs to test them. This is Step 5 (Test) of the AI Workflow Framework.
development
This skill should be used when the user has built and tested workflow artifacts and wants a Run Guide for deploying and operating their AI workflow. It generates a plain-language guide with setup steps, deployment patterns, and sharing instructions — tailored to the user's platform and build path. This is Step 6 (Run) of the AI Workflow Framework.
development
Evaluate a running AI workflow for quality, relevance, and evolution opportunities. Use when the user wants to review how a deployed workflow is performing, check if it needs tuning, or assess whether it should graduate to a more capable orchestration mechanism. This is Step 7 (Improve) of the AI Workflow Framework.