# Gaming Device Power Management Agent Skill

> A Claude skill from dungnotnull/gaming-device-power-management-agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-gaming-device-power-management-agent-skill-gaming-device-power-management-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/gaming-device-power-management-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-gaming-device-power-management-agent-skill-gaming-device-power-management-agent-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```markdown
---
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
```python
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
```python
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
```python
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 `HookEvent`s 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`.

```python
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)**
```json
{"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)**
```json
{"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`.

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

---

## 9. CLI

```bash
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.
2. **Add a tool:** write a handler in `src/gdpm/tools/builtins.py`, register a
   `Tool` with schemas in `build_default_registry()`.
3. **Add a hook:** `bus.register(HookPhase., handler, priority=N)`.
4. 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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/gaming-device-power-management-agent-skill](https://github.com/dungnotnull/gaming-device-power-management-agent-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dungnotnull-gaming-device-power-management-agent-skill-gaming-device-power-management-agent-skill
- Seller: https://agentstack.voostack.com/s/dungnotnull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.