Create Agentic Skills that can be used in claude code/codex/opencode but run Agentic Orchestration systems

[CraftsMan-Labs]

Native Skills for SimpleAgents Orchestration

• Owner: SimpleAgents Platform
• Status: Draft v1
• Target: Local + Cloud (Cloud Code Agents, Deep Research-style agents)
• Primary UX Goal: “Create skill.yaml + handlers.py, install once, run skill.”
  Problem
• Users can build workflows, but packaging reusable orchestration as an easy “skill” is not yet first-class.
• Sensitive operations need admin approval gates with auditable lifecycle.
• Large runs need node-level recovery without rerunning full workflow.
• Multimodal workflows (images/videos) need first-class transport and handling across the full pipeline.
• Teams need one correlated transaction view in telemetry (Jaeger/Langfuse/OTLP) for governance/debugging.
  Vision
• Skills are reusable orchestration units that can be created, validated, installed, executed, and observed consistently across Rust/Python/Node/Go and cloud execution targets.
• A skill run is a traceable transaction with approvals, retries, and media references all correlated.
  Primary Users
• Workflow builders (engineers/AI operators)
• Platform teams (compliance, reliability)
• Product teams using cloud agents (deep research, task automation)
  Success Metrics
• Time to first skill run: < 10 minutes from template.
• Skill execution success rate (non-user error): > 95%.
• Approval trace completeness: 100% lifecycle events emitted.
• Resume efficiency: failed-node retry avoids full rerun in > 90% eligible failures.
• Cross-binding parity: all contract tests pass in Rust/Python/Node/Go.
  In Scope (MVP+)
• Skill packaging and execution (skill.yaml + handlers.py)
• Approval gates (required, audit) with history-backed persistence (DB-optional V1)
• Node-scoped resume/retry from checkpoint
• Image/video references across workflow nodes
• Unified telemetry correlation for one workflow transaction
  Out of Scope (V1)
• Rich visual skill editor UI
• Full marketplace/discovery UX
• Built-in long-term DB analytics (can add via adapter later)
• Inline large binary transport as default (reference-based only)
  User Experience
• Create skill:
  • Write skill.yaml
  • Implement custom logic in handlers.py
  • Run simple-agents skill install ./my_skill
• Run skill:
  • simple-agents skill run my_skill --input input.json
• If blocked by approval:
  • Admin resolves approval
  • Continue run with continue_run(run_id)
• Output:
  • Structured result + run_id + trace_id + events + artifacts/media refs
    Functional Requirements
• Skill Lifecycle
• create_skill from template or prompt-draft
• validate_skill with schema and handler checks
• install/register_skill versioned and immutable by default
• run_skill with typed input/output contracts
• list_skills, get_skill, publish_skill (for cloud registry phase)
• Approval Workflow
• Tool-level approval metadata in YAML:
  • type: required|audit
  • primitive: requires_confirmation|requires_user_input|external_execution
• Required mode pauses run and emits pending approval event/record
• Audit mode continues run and logs audit event
• CAS-safe resolution with expected_status="pending"
• Continue path validates approval resolution before proceeding
• Node-Scoped Retry
• On eligible failure, persist checkpoint with failed_node_id and continuation state
• resume_from_failure(run_id|checkpoint_id) resumes from failed segment, not entry node
• Idempotency guardrails for side-effect nodes/tools
• Retry attempt metadata captured in events/telemetry
• Image/Video Across Workflow
• Add multimodal message/content-part model
• Pass media by MediaRef (not raw bytes) through input/node outputs/globals
• Support image/video tool and LLM paths
• Validate MIME/size and apply safety limits
• Telemetry Correlation (Mandatory)
• One transaction lineage across all lifecycle states
• Stable correlation fields:
  • trace_id, run_id, workflow_id, skill_id, skill_version, node_id
  • approval_id, media_id, tenant/request fields when present
• Required events include skill, approval, retry, and media lifecycle transitions
• OTLP-first attributes with Jaeger/Langfuse compatibility
  Technical Design Summary
• Rust Source of Truth
• New skill domain crate/module with manifest, registry, runner façade
• Extend workflow runtime for paused outcomes and resume paths
• Approval storage abstraction with history-backed V1 implementation
• Media storage abstraction with local/in-memory adapters in V1
• YAML schema/validator expanded for skill + approval + multimodal configs
• Bindings
• Python/Node/Go expose identical lifecycle APIs:
  • run_skill, continue_run, resume_from_failure, update_approval, media helpers
• Maintain backward compatibility for existing text-only workflows
• Strong typed contracts in .pyi, .d.ts, Go structs
• Cloud Adapters
• Runtime adapter layer for local and cloud backends
• Same skill contract, different execution transport
  API/CLI Surface (Target)
• CLI:
  • simple-agents skill install
  • simple-agents skill validate <skill.yaml>
  • simple-agents skill run <skill_id> --input
  • simple-agents run continue --run-id
  • simple-agents run resume-failure --run-id
• SDK (all bindings parity):
  • run_skill(...)
  • continue_run(run_id, requirements?)
  • resume_from_failure(run_id|checkpoint_id, options?)
  • list_pending_approvals(...)
  • update_approval(...)
    YAML Contract (Representative)
• Skill file includes:
  • identity/version metadata
  • input/output schemas
  • workflow nodes/edges
  • tool definitions and optional approval blocks
  • optional multimodal message parts and media refs
  • runtime/telemetry defaults
    Non-Functional Requirements
• Reliability: typed errors, deterministic transitions
• Safety: explicit status transition checks, no hidden retries
• Performance: reference-based media transport, bounded payloads
• Security: no raw sensitive media in telemetry by default
• Governance: auditable events for approvals and resume actions
  Milestones
• M1: Skill manifest + install/validate/run (local)
• M2: Approval required/audit + continue semantics
• M3: Node-scoped retry/resume formalized across bindings
• M4: Multimodal image/video refs end-to-end
• M5: Telemetry hardening + Jaeger/Langfuse validation + docs/cookbooks
• M6: Cloud execution adapters and registry integration
  Acceptance Criteria
• User can run a skill from skill.yaml + handlers.py with one install + one run command
• Required approvals pause and resume correctly; audit mode logs without pause
• Failed node resumes without full rerun where checkpoint exists
• Image/video refs pass across workflow and are consumable by supported providers/tools
• Telemetry shows one correlated transaction lineage for full run lifecycle
• Rust/Python/Node/Go parity tests pass
  Risks and Mitigations
• Contract drift across bindings
• Mitigation: contract fixtures and parity CI gates
• Media payload bloat
• Mitigation: enforce reference-first transport and hard limits
• Resume side-effect duplication
• Mitigation: idempotency keys and explicit retry policy controls
• Approval race conditions
• Mitigation: CAS updates with expected_status enforcement
  Documentation Deliverables
• Skill authoring guide (skill.yaml + handlers.py)
• Approval lifecycle guide
• Resume/retry operations guide
• Multimodal workflow guide (image/video refs)
• Telemetry correlation guide (Jaeger/Langfuse/OTLP)
• End-to-end examples in Rust/Python/Node/Go
  Open Decisions to Finalize
• Default versioning policy (latest allowed or pinned-only in prod)
• Default media store for local runtime (filesystem path conventions)
• Cloud registry ownership and tenancy model
• Whether prompt-to-skill generation ships in MVP or Phase 2