Gaming Device Power Management Agent Skill

SKILL.md — Skill Registry Documentation

> gaming-device-power-management v2.0.0 — the canonical reference for how > skills, tools, hooks, and agents are registered, resolved, executed, and > validated in this harness. This document is the contract between the > markdown skill definitions (skills/*.md) and the executable agent runtime > (src/gdpm/).

---

1. Overview

The harness is a modular skill-registry architecture with four cooperating subsystems:

| Subsystem | Module | Responsibility | |-----------|--------|----------------| | SkillRegistry | gdpm.registry | Load/resolve/validate skill definitions from skills/*.md | | Router | gdpm.router | Chain-of-thought routing over the 6-step pipeline | | ToolRegistry | gdpm.tools | JSON-schema-validated, executable tool handlers | | Hooks | gdpm.hooks | Lifecycle management, state sync, event emission | | Agents | gdpm.agents | Five specialized sub-agents (LLM + deterministic fallback) | | Orchestrator | gdpm.orchestrator | Drives the pipeline, quality gates, graceful degradation |

A run flows: query → language detect → router → agents (with hooks + tools + context budget) → quality gates → result.

---

2. Skill Registration

2.1 Skill file format

Every skill is a markdown file in skills/ with YAML frontmatter:

---
name: sub-core-analysis
description: Optimize power management for gaming devices ...
---

## Role & Persona
...
## Workflow
...
## Output Format
...
## Quality Gates
...

• main.md is classified as kind: main; all other *.md are kind: sub.
• Frontmatter is parsed by a dependency-free parser (gdpm.models.parse_frontmatter)

that extracts flat key: value pairs (name, description).

2.2 Required sections

| Kind | Required sections | |------|-------------------| | main | Role & Persona, Harness Execution Protocol, Quality Gates, Graceful Degradation, Sub-skills Available, Output Format | | sub | Role & Persona, Workflow, Output Format, Quality Gates |

SkillRegistry.validate() reports any missing section as a violation.

2.3 Tool reference extraction

The registry heuristically scans each skill body for recognized tool names (WebSearch, WebFetch, Read, Write, Bash, Skill, Conversation, Arithmetic, Reasoning) and records them in SkillDef.tools for the manifest.

2.4 Programmatic registration

from gdpm.registry import SkillRegistry
registry = SkillRegistry("skills")
main = registry.main()                 # SkillDef | None
sub = registry.get("sub-core-analysis")  # raises SkillNotFoundError if absent
violations = registry.validate()       # list[str], empty = ok
manifest = registry.manifest()         # machine-readable JSON

---

3. Resolution & Routing

3.1 The fixed pipeline

PIPELINE = [
    "sub-gather-requirements",   # step 1
    "sub-evidence-collector",    # step 2
    "sub-core-analysis",         # step 3
    "sub-knowledge-updater",     # step 4
    "sub-advisor",               # step 5
    "__quality_gate__",          # step 6
]

3.2 Chain-of-thought router

gdpm.router.Router emits a RoutingDecision carrying an explicit thought trace for every decision. Beyond the fixed order it can:

• Skip evidence collection when the user supplied a complete evidence bundle

(state.evidence._user_supplied + current_data + authoritative_docs).

• Repeat sub-gather-requirements when the object of analysis is missing.
• Re-run sub-knowledge-updater only when gaps were flagged.
• Cap visits per step (max_visits_per_step, default 2) to prevent loops,

raising QualityGateError when exhausted.

Routing is deterministic and unit-tested; a live LLM router can subclass Router and override route().

---

4. Tools

4.1 Tool contract

Each tool is a Tool(name, description, input_schema, output_schema, handler, tags, read_only). Inputs and outputs are validated against a dependency-free JSON-Schema subset (gdpm.tools.validate_schema): type, enum, required, properties, items, minimum/maximum, minLength, minItems.

4.2 Built-in tools

| Tool | Input (key fields) | Output (key fields) | Degrades? | |------|--------------------|---------------------|-----------| | detect_language | text | language, confidence | no | | read_knowledge_brain | query, max_results | matches, total, online, limitation | yes (offline) | | compute_playtime | battery_wh, draw_w, reserve_pct | hours, usable_wh, formula | no | | estimate_drain_share | component, draw_w, total_draw_w | share_pct | no | | battery_aging_estimate | dod_pct, avg_temp_c, cycles, charge_limit_pct | capacity_retention_pct, notes | no | | assign_tier | source, venue, citation_count | tier | no | | score_entry | title, abstract, keywords, citation_count, year | score | no | | web_search | query, max_results | results, online, limitation | yes (offline) | | web_fetch | url, max_chars | content, status, online, limitation | yes (offline) | | format_evidence | items | bundle, count, has_academic | no |

4.3 Invocation

from gdpm.tools import build_default_registry
reg = build_default_registry("SECOND-KNOWLEDGE-BRAIN.md")
reg.invoke("compute_playtime", {"battery_wh": 40, "draw_w": 12})
# -> {"hours": 3.17, "usable_wh": 38.0, "formula": "...", "reserve_pct": 5.0}

Schema violations raise ToolValidationError; handler failures raise ToolExecutionError. Both are caught by the orchestrator's fallback policy.

4.4 Schemas

Authoritative JSON schemas live in assets/schemas/: skill.schema.json, tool.schema.json, hook.schema.json, run-result.schema.json.

---

5. Hooks

gdpm.hooks.HookBus dispatches HookEvents to handlers per phase. Phases: pre_run, post_run, pre_step, post_step, on_error, on_degrade, on_gate. Handlers run in priority order (lower first); the first non-None HookDecision short-circuits.

Built-in hooks (installed by install_default_hooks):

• LoggingHook — structured JSON log per event.
• EventEmissionHook — pushes events to an EventBuffer for testing/dashboards.
• LimitationCollectorHook — accumulates limitations on on_degrade.
• StateSynchronizerHook — mirrors run state to logs/run_state.json.

from gdpm.hooks import HookBus, HookPhase, install_default_hooks
bus = HookBus()
install_default_hooks(bus, event_buffer=buf, state_path="logs/run_state.json")
bus.register(HookPhase.ON_GATE, my_handler, priority=50, name="my_gate_hook")

---

6. Agents & Execution

6.1 Sub-agent contract

Each SubAgent implements:

• _local(state) — deterministic offline path (always succeeds).
• _llm_prompt(state) — optional (system, user) prompts for the LLM path.
• _check_gate(output) — internal quality gate.
• _mutate_state(state, output) — merges output into the run state.

SubAgent.run() tries the LLM path (if a non-NullLLMClient is configured), and falls back to _local on LLMError, recording the failure as a limitation. This is the production graceful-fallback guarantee: the harness always produces a structured result.

6.2 The five agents

| Step | Agent | State mutation | |------|-------|----------------| | 1 | GatherRequirementsAgent | state.requirements | | 2 | EvidenceCollectorAgent | state.evidence, state.degradation | | 3 | CoreAnalysisAgent | state.core_analysis | | 4 | KnowledgeUpdaterAgent | state.knowledge | | 5 | AdvisorAgent | state.verdict |

6.3 Run state I/O schemas

Step outputs are JSON-serializable dicts. Representative shapes:

Requirements (step 1)

{"object": "Steam Deck", "scope": {"playtime_target_h": 2.0, "performance_floor": "..."},
 "timeframe": "single-session sustained use",
 "available_inputs": {"battery_wh": null, "tdp_range_w": null, "refresh_rate_hz": null,
                      "thermal_data": null, "game_title": "AAA"},
 "target_audience": "practitioner", "language": "vi", "analysis_type": "combined",
 "clarifying_questions": [], "assumptions": ["analysis_type defaulted to 'combined'"]}

Verdict (step 5)

{"verdict": "Conditional (tradeoff)",
 "scenarios": {"best": {...}, "base": {...}, "worst": {...}},
 "key_risks": [{"risk": "...", "probability": "M", "impact": "M", "evidence": "..."}],
 "evidence_chain": [{"claim": "...", "source": "...", "tier": "1"}],
 "remediation": ["..."], "disclosure": "...", "playtime_h": 3.17, "total_draw_w": 12.0}

The full run result conforms to assets/schemas/run-result.schema.json.

---

7. Quality Gates

gdpm.gates implements U1–U6 (universal) and G1–G4 (domain) as pure functions over RunState. The orchestrator runs them after the pipeline, auto-fixes what it can, and records residual limitations. See references/prompt-templates/quality-gates.md.

---

8. Configuration

config/*.toml (default, llm, feature_flags) loaded by gdpm.settings.load_settings() into typed dataclasses, with environment-variable overrides (GDPM_*). Validation fails fast via ConfigurationError.

GDPM_MAX_TOKENS=60000 GDPM_LLM_ENABLED=false python -m gdpm.cli run "..."

---

9. CLI

gdpm run ""            # run the harness, emit JSON result
gdpm validate                 # registry validation + smoke run
gdpm list                     # list registered skills
gdpm manifest                 # emit registry manifest JSON
gdpm crawl [--dry-run]        # run the knowledge crawl pipeline

---

10. Validation & Testing

• tools/validate_project.py — 8-File Contract validator (CI entry).
• tools/run_test_scenarios.py — structural & content validator.
• tools/test_knowledge_updater.py — knowledge pipeline unit tests.
• tests/unit/ — pytest suite for the gdpm package (registry, router, tools,

hooks, gates, agents, orchestrator, settings).

• scripts/validate_all.py — runs everything + ruff + mypy.

---

11. Extending the registry

1. Add a sub-skill: create skills/sub-.md with frontmatter + the four

required sections; add an agent in src/gdpm/agents/ implementing SubAgent; register it in build_agents() and add it to Router.PIPELINE if it belongs in the pipeline.

1. Add a tool: write a handler in src/gdpm/tools/builtins.py, register a

Tool with schemas in build_default_registry().

1. Add a hook: bus.register(HookPhase., handler, priority=N).
2. Re-run scripts/validate_all.py and scripts/generate_manifest.py.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/gaming-device-power-management-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.