penguiflow-runtime-skills-pack

name

penguiflow-runtime-skills-pack

description

Author "skill packs" — playbooks the PenguiFlow ReactPlanner retrieves at runtime via `skill_search`/`skill_get`/`skill_list` (NOT the same as the SKILL.md agent-tool descriptors in the project's `skills/` directory; these are runtime artifacts stored in a SQLite skill store). Configure `SkillsConfig(enabled=True, skill_packs=[SkillPackConfig(...)], top_k=..., redact_pii=True)`, pick a pack format (`*.skill.md`/`.yaml`/`.json`/`.jsonl`), declare applicability via `required_tool_names`/`required_namespaces`/`required_tags`, scope by tenant/project, compose with a runtime `skills_provider`/`skills_provider_factory`, optionally enable non-persisting `skill_propose` drafting and `SkillsDirectoryConfig` surfacing. Use when a user says "author a skill pack", "playbooks for my planner", "skill_search", "runtime skills provider", or names `SkillsConfig`.

Authoring Runtime Skill Packs for the Planner

Important: naming collision (read first)

This skill is about planner-consumed skill packs — curated playbooks that the LLM retrieves at runtime via skill_search / skill_get / skill_list tools. These are PenguiFlow runtime artifacts stored in a SQLite skill store and rendered into prompts.

These are NOT the same as the SKILL.md files inside the project's skills/ directory. Those are agent-tool skill descriptors following the agentskills.io / Anthropic Skills bundle format (used by the AI tooling that reads this very file). The two share the word "skill" but live in completely different layers:

Layer	What it is	Format	Audience
Agent skills (this directory)	Tool descriptors for AI assistants	SKILL.md + frontmatter + references/* + agents/openai.yaml	The AI assistant reading the skill
Planner skill packs (this skill)	Playbooks the ReactPlanner retrieves	*.skill.md/.skill.yaml/.skill.json/.skill.jsonl	The LLM driving the planner at runtime

Don't try to reuse SKILL.md files as planner skill packs (or vice versa). Different schemas, different consumers.

When to use

• Codify operational procedures ("how we handle an incident") as planner-retrievable playbooks.
• Standardize agent behavior across teams without copy-pasting prompt text.
• Surface domain conventions (titles, layouts, when to use which chart) to the planner.
• Author tenant- or persona-specific guidance gated by applicability.

When NOT to use

• Long-term memory or knowledge base → not the right tool; build retrieval separately.
• Tools — skills are documents, they don't execute.
• Frequently-changing data — packs are versioned like code, not live data.
• Trying to override planner configuration knobs — that's [[penguiflow-reactplanner-config]].

Hard boundaries

This skill covers authoring and configuring runtime skill packs and the providers that supply them. Planner knobs (always-visible tools, ToolPolicy, etc.) live in penguiflow-reactplanner-config. Rich-output integration with skills lives in penguiflow-rich-output.

Workflow

1) Decide static packs vs runtime provider

Choice	Use when
Static packs (skill_packs=[...])	In-repo curated playbooks, versioned with code.
Runtime provider (skills_provider=...)	Per-user personas, dynamic content from a host service.
Both	Static packs as the baseline, runtime overlays for tenant-specific guidance. Runtime wins on name collision.

2) Author a pack

Pick a format: *.skill.md (Markdown + YAML frontmatter, most readable), *.skill.yaml/.yml, *.skill.json, *.skill.jsonl (bulk import). Required frontmatter: trigger (when to use), steps (the playbook). Recommended: name, title, task_type, applicability (required_tool_names/required_namespaces/required_tags), failure_modes. Full schema and a runnable Markdown example in references/pack-formats.md.

3) Wire SkillsConfig

SkillsConfig(
    enabled=True,                            # default False; must opt in
    cache_dir=".penguiflow",                 # library default; SQLite store location
    skill_packs=[SkillPackConfig(name="ops", path="skills/packs/ops")],
    top_k=6,                                 # default
    max_tokens=2000,                         # default (range 200-10000)
    summarize=False,                         # default
    redact_pii=True,                         # default
)

Planner gets skill_search/skill_get/skill_list always-visible plus pre-flight injection of top_k relevant skills.

4) (Optional) Wire a runtime provider

class TenantSkillProvider(SkillProvider):
    # Six required methods — typed queries + keyword-only tool_context/capability_context.
    async def get_relevant(self, query, *, tool_context, capability_context=None): ...
    async def search(self, query, *, tool_context, capability_context=None): ...
    async def get_by_name(self, names, *, tool_context, capability_context=None): ...
    async def list(self, req, *, tool_context, capability_context=None): ...
    async def directory(self, config, *, tool_context, capability_context=None): ...
    async def format_for_injection(self, skills, *, max_tokens): ...

planner = ReactPlanner(
    ...,
    skills_provider=TenantSkillProvider(),      # or skills_provider_factory=Callable[[SkillsConfig], SkillProvider]
    skills=SkillsConfig(enabled=True, skill_packs=[...]),  # static packs compose
)

Runtime providers are Python-only — use for per-tenant skills loaded from a host service, user personalization, or composition with the host app's permission model. Static packs and runtime providers compose; runtime wins on name collision.

5) Scope per tenant/project

Pass tenant_id, project_id, user_id in tool_context — the provider scopes by these. Without them, scope filtering is permissive (fine for single-tenant, dangerous for multi-tenant).

6) Use applicability metadata

Per-skill required_tool_names / required_namespaces / required_tags. The planner checks against the request's allowed capability set (after tool policy/visibility) — skill surfaces only when all populated requirements are satisfied. Use for persona-style and capability-gated skills.

7) (Optional) skill_propose drafting and directory

SkillsConfig(..., proposal={"enabled": True}) exposes a non-persisting drafting tool. SkillsDirectoryConfig(enabled=True, include_fields=[...]) surfaces a compact directory for discoverability.

8) Treat packs as LLM-visible

Anything in a skill enters llm_context. No secrets, no PII, no tenant-private identifiers. redact_pii=True is a safety net, not a substitute for clean authoring.

Troubleshooting (fast checks)

• skill_search is not configured — SkillsConfig.enabled=False, or no provider. Enable and verify packs load.
• skill_propose is not configured — proposal.enabled=False; enable it explicitly.
• Pack ignored / no skills available — path doesn't exist on the worker (container vs laptop), or YAML frontmatter invalid (empty trigger/steps).
• Skill surfaces but mentions a forbidden tool — applicability misconfigured; add required_tool_names or rewrite the skill to use tool_search.
• Cross-tenant skill leak — tenant_id/project_id not in tool_context; the provider has nothing to scope on.
• Runtime provider not appearing — confirm both skills_provider is injected AND SkillsConfig.enabled=True (passing a provider with enabled=False is a configuration error).
• Top-k retrieval misses obvious skills — bad trigger text; rewrite to mention the user's intent terms.
• Skills bloat prompts — lower max_tokens and top_k; enable summarize=True.

Worked example

• examples/planner_enterprise_agent/ and examples/planner_enterprise_agent_v2/ use skill packs in their planner setup; inspect their skills/ subdirectory for canonical pack layouts.

References (load only as needed)

• references/pack-formats.md — every supported format with full schemas, applicability fields, validation rules.
• references/providers-and-scoping.md — SkillProvider protocol, runtime providers, composition with local packs, tenant scoping, host-side ACL patterns.
• references/retrieval-and-tools.md — skill_search/skill_get/skill_list, pre-flight injection, directory rendering, tool-aware redaction, skill_propose lifecycle.