skills_executor

Skills Executor Examples

These examples use Agently.skills_executor and the standard SKILL.md model: a Skill is guidance plus optional execution metadata in frontmatter (execution: staged, allowed-tools, stages, max-steps). There is no skill.yaml and no custom stage schema. The default strategy is single_shot; staged and react run on TriggerFlow and tool/action calls delegate through Action / ActionRuntime. Side effects such as file writes, network calls, package installation, and durable approvals remain owned by host code, Action, ExecutionEnvironment, or TriggerFlow.

Self-authored example Skills live as real standard Skill directories under examples/skills_executor/skills/<skill-id>/SKILL.md. Example scripts install those directories; they do not construct inline SKILL.md strings or generate root-level YAML manifests at runtime.

Configure the registry once with the public API:

Agently.skills_executor.configure(registry_root=..., allowed_trust_levels=["local"])

Example	Purpose
01_basic_declarative_skills.py	Model-free smoke test: install a standard SKILL.md, inspect the normalized contract, and resolve a deterministic required plan (registry + planner mechanics, no model call).
02_deepseek_external_skill_cards.py	Declare real external SKILL.md sources (Anthropic + Agently-Skills) through agent.use_skills(...); the planner lazily discovers/materializes the selected remote Skill and DeepSeek applies its guidance.
03_stock_research_business_minimal.py	Minimal business sample: the host fetches live quotes (Stooq), then remote OctagonAI + Anthropic Skills provide stock-research and artifact guidance for a structured brief.
04_dynamic_todo_triggerflow_realcase.py	Diagnostic realcase: expose Agently-Skills guidance to DeepSeek and check whether it can generate a runnable dynamic TriggerFlow Todo-DAG without prompt-level API hints.
05_combo_skillpack_diagnostics.py	Combo Skill Pack diagnostics across five realcase packs (education, stock, travel, research-to-briefing, webapp acceptance).
06_executable_education_course_pack.py	Remote GarethManning education Skills + Anthropic docx/pdf/pptx/xlsx Skills produce structured course content; the host writes real artifacts (libraries host-managed, skipped if missing).
07_agently_skills_availability_check.py	Developer pre-flight: install the local ../Agently-Skills catalog and verify explicit-selection eligibility.
08_architecture_diagram_skill.py	A prompt-first architecture-diagram Skill renders a self-contained dark-themed HTML+SVG diagram; the host writes the file.
09_runtime_planner_effort_strategy.py	Real-model runtime planner demo: effort="fast" takes the low-cost single_shot path; effort="normal" runs the complete preflight → research → plan → execute → verify → reflect → finalize chain with model-pool stage routing.
10_model_pool_key_pool_resolution.py	Public model-pool/key-pool resolution probe: model_key routes model and key settings through real request and Skills context calls.

The new-standard shape

# Local authoring path: Skill = SKILL.md guidance plus optional standard frontmatter
Agently.skills_executor.configure(registry_root=reg_dir, allowed_trust_levels=["local"])
contract = Agently.skills_executor.install_skills(skill_dir, trust_level="local", update=True)
skill_id = contract["skill_id"]          # slug of the frontmatter `name`

# 2. Default single_shot request; structured output via output
execution = await agent.async_run_skills_task(
    task,
    skills=[skill_id],
    mode="required",                      # default is "model_decision"
    output={"summary": (str, "..."), "items": ([str], "...")},
    stream_handler=on_stream,             # optional: field-level streaming
)

# 3. Host owns side effects; TriggerFlow/Action own orchestration/acting paths
result = execution.output
write_file(result["summary"])             # persistence is host code

• mode defaults to "model_decision" (the planner asks the model which Skills to use and in what order). Pass mode="required" to force-select known Skills.
• Reference Skills by the skill_id returned from install_skills(...) — it is the slug of the frontmatter name (e.g. "Release Notes Generator" → "release-notes-generator").
• To stream field-level progress, use async_run_skills_task(..., stream_handler=...) and filter items where type == "skills.model_stream" and is_complete.
• To select quality/cost profiles, pass effort="fast" | "normal" | "max" to async_run_skills_task(...). Advanced callers can override presets with agent.set_settings("effort_presets", {...}).

For remote/public Skills, the recommended business path is declaration, not request-path preinstallation:

agent.use_skills(
    [{"source": "anthropics/skills", "subpath": "skills/docx", "trust_level": "remote"}],
    mode="required",
)

execution = await agent.async_run_skills_task(
    "Draft a client-ready incident report as a docx package.",
    mode="required",
    effort="normal",
    output={...},
)

install_skills_pack(...) remains useful for prewarming/offline mirrors, CI fixtures, and explicit local pool maintenance.

Minimal business shape — host tool + prompt-only Skill

03_stock_research_business_minimal.py keeps the visible code close to how an application developer would use the feature. The controlled side effect (fetching quotes) runs in the host, before model analysis. Research guidance comes from remote OctagonAI Skills; artifact guidance comes from Anthropic Skills:

agent.use_skills([
    {"source": "OctagonAI/skills", "subpath": "skills/market-analyst-master"},
    {"source": "OctagonAI/skills", "subpath": "skills/financial-analyst-master"},
    {"source": "OctagonAI/skills", "subpath": "skills/sec-analyst-master"},
    {"source": "OctagonAI/skills", "subpath": "skills/earnings-analyst-master"},
    {"source": "anthropics/skills", "subpath": "skills/docx"},
    {"source": "anthropics/skills", "subpath": "skills/xlsx"},
], mode="required")

market_data = fetch_equity_market_data("NVDA, AMD, AVGO")   # host tool, real I/O

execution = agent.run_skills_task(
    f"Analyze NVDA/AMD/AVGO. market_data: {market_data}",
    mode="required",
    effort="normal",
    output={...},
)
result = execution.output

It uses Stooq's CSV quote endpoint (no API key needed); provider timestamps may be delayed and are not exchange-direct realtime ticks. The output is explicitly research-only and excludes buy/sell/hold/order instructions.

Environment

Model examples load .env themselves. DEEPSEEK_API_KEY can be in the shell or a .env file; set DYNAMIC_TASK_MODEL_PROVIDER=ollama to use a local Ollama endpoint instead. 01_basic_declarative_skills.py needs no model.

02_deepseek_external_skill_cards.py uses agent.use_skills(...) remote source selectors. Selectors accept GitHub shorthand (anthropics/skills, AgentEra/Agently-Skills) with subpath, or local checkouts from ANTHROPIC_SKILLS_REPO / AGENTLY_SKILLS_REPO. The planner discovers and installs only when the source is selected.

06_executable_education_course_pack.py writes Office artifacts when the optional libraries are installed (pip install python-docx reportlab python-pptx openpyxl); each artifact is skipped gracefully if its library is missing. The example does not install packages at runtime — dependencies are the host's responsibility.

Commands

python examples/skills_executor/01_basic_declarative_skills.py   # no model needed
python examples/skills_executor/02_deepseek_external_skill_cards.py
python examples/skills_executor/03_stock_research_business_minimal.py
python examples/skills_executor/04_dynamic_todo_triggerflow_realcase.py
python examples/skills_executor/05_combo_skillpack_diagnostics.py --fetch-missing
python examples/skills_executor/06_executable_education_course_pack.py
python examples/skills_executor/07_agently_skills_availability_check.py
python examples/skills_executor/08_architecture_diagram_skill.py
python examples/skills_executor/09_runtime_planner_effort_strategy.py
python examples/skills_executor/10_model_pool_key_pool_resolution.py

Skills test suite:

PYTHONPATH=. python -m pytest -q tests/test_skills_executor.py tests/test_skills_executor_real_anthropic_skills.py