Private Game Server Automation Agent Skill

SKILL.md — Skill Registry Documentation

> This document explains how the private-game-server-automation harness > registers, resolves, executes, and validates sub-skills. It is the > canonical reference for tooling authors extending the harness.

1. Discovery Model

The runtime component tools/skill_registry.py:SkillRegistry scans skills/*.md for files beginning with YAML frontmatter and registers each as a SkillManifest. There is no manual registration list — adding a new .md file under skills/ automatically makes it discoverable.

Required Frontmatter

---
name: sub-             # unique identifier (matches file stem)
description:    # used for triggering; keep -schema.json
tags: [specialist, ]
---

name, description are required; the other keys are optional but recommended. The registry parses frontmatter without a full YAML dependency (see _parse_simple_frontmatter); only scalars and inline lists are supported.

2. Skill Tiers

Skills are classified by file stem into one of these tiers:

| Tier | File stem pattern | Examples | |------|-------------------|----------| | main | main.md | main.md | | router | sub-router.md | sub-router.md | | intake | sub-gather-requirements.md | sub-gather-requirements.md | | evidence | sub-evidence-collector.md | sub-evidence-collector.md | | specialist | sub-provisioning.md, sub-networking.md, sub-security.md, sub-observability.md, sub-cost-optimizer.md | 5 specialists | | knowledge | sub-knowledge-updater.md | sub-knowledge-updater.md | | advisor | sub-advisor.md | sub-advisor.md | | legacy | sub-core-analysis.md | sub-core-analysis.md | | other | anything else | (none currently) |

Tier drives routing and validation. Specialists are dispatched in parallel by default; router / intake / evidence / knowledge / advisor run sequentially.

3. Resolution

Resolution is by exact name match. The orchestrator (skills/main.md) uses Skill("sub-provisioning") style invocations; the harness's runtime counterpart SkillRegistry.dispatch(name, inputs=...) returns a JSON envelope describing the dispatch:

{
  "skill": "sub-provisioning",
  "tier": "specialist",
  "inputs": {"requirements": {...}, "evidence_bundle": {...}},
  "missing_required_inputs": [],
  "schema_uri": "assets/schemas/analysis-result-schema.json",
  "instructions_file": "skills/sub-provisioning.md"
}

missing_required_inputs is populated by intersecting the manifest's declared inputs with the supplied inputs dict. The orchestrator decides whether to block or proceed with flags.

4. Execution

Execution of a sub-skill means "Claude reads the markdown body and follows its instructions". The runtime does NOT execute skill bodies as code. This is intentional: skills are LLM instructions, not Python.

The lifecycle is:

orchestrator (main.md)
  |
  |--> pre_execution hook
  |--> Skill("sub-gather-requirements")  -> Requirements
  |--> Skill("sub-evidence-collector")   -> EvidenceBundle
  |--> Skill("sub-router")               -> RouterDecision
  |--> for each specialist in RouterDecision.selected_specialists (parallel or sequential):
  |       Skill("sub-")      -> SpecialistAnalysisResult
  |       state_sync.snapshot(...)
  |--> Skill("sub-knowledge-updater")    -> KnowledgeBundle
  |--> Skill("sub-advisor")              -> AdvisorConclusion
  |--> quality gate reviewer             -> report + gate_results
  |--> post_execution hook
  |--> deliver report

5. Validation

The registry exposes validate_registry() which performs cross-skill sanity checks and returns a list of issues (empty = healthy):

• The orchestrator file skills/main.md must exist.
• A router skill sub-router.md must exist.
• All 5 specialists must be present: sub-provisioning,

sub-networking, sub-security, sub-observability, sub-cost-optimizer.

• Every skill has a non-empty description.
• No skill description exceeds 1024 characters (Claude Code's limit).

Per-skill output validation against JSON schemas lives in tools/skill_registry.SkillManifest.schema_uri and is enforced by the orchestrator's gate review step, not by the registry itself. Schemas live in assets/schemas/.

6. JSON Schemas

| Schema | Used by | |--------|---------| | requirements-schema.json | sub-gather-requirements | | evidence-bundle-schema.json | sub-evidence-collector | | router-decision-schema.json | sub-router | | analysis-result-schema.json | sub-provisioning / sub-networking / sub-security / sub-observability / sub-cost-optimizer / sub-core-analysis (legacy) | | advisor-conclusion-schema.json | sub-advisor | | server-config-schema.json | tools/server_manager.py |

All schemas use JSON Schema Draft 2020-12 and are referenced by $id so they can be fetched cross-repo. The harness validates outputs against these schemas in the quality gate step using jsonschema (or a structural fallback in environments without it).

7. Adding a New Specialist

1. Pick a name. Convention: sub-.
2. Write skills/sub-.md with the required frontmatter.
3. Write assets/schemas/-schema.json (or reuse

analysis-result-schema.json if it fits).

1. Update tools/skill_registry._SPECIALTY_KEYWORDS if the file stem does

not contain the literal specialty name.

1. If the specialist must always be present, add it to

SkillRegistry.validate_registry.

1. Update skills/main.md's "Sub-skills Available" table.
2. Update tests/test_skill_registry.py to assert the new skill loads.

8. Adding a New Hook

1. Pick a lifecycle point: pre-execution / post-execution / state-sync /

event subscriber.

1. Implement the hook in hooks/.py exposing a top-level callable.
2. Hooks MUST NOT raise into the harness; wrap risky operations in

tools/error_handler.safe_call and log via tools/structured_logger.

1. Update hooks/__init__.py to re-export the public surface.
2. Add tests in tests/test_hooks.py.

9. Configuration Surface

Skills read configuration via the config package:

from config import get_settings, FeatureFlags

settings = get_settings()
if FeatureFlags.is_enabled("enable_chain_of_thought_router"):
    ...

Configuration is layered: config/default.toml -> config/.toml -> PGSA_-prefixed environment variables. The config/settings.py module validates every section against a typed dataclass and refuses to start when required keys are missing.

10. Token Budget

The harness tracks token usage via tools/token_manager.TokenManager. The orchestrator calls .plan(stage, projected_input) before each sub-skill invocation and receives one of four actions:

| Action | Meaning | |--------|---------| | proceed | Within budget; run as-is. | | summarise_prior | Approaching budget; fold older stages into a summary. | | shed_oldest | Critical; drop oldest stage from context. | | refuse | Cannot fit; refuse the call rather than truncate silently. |

The orchestrator's behaviour on refuse is to switch to a degraded mode (Level >= 3) and emit a limitation banner rather than produce a half-formed output.

11. Hooks Contract

| Hook | When | Side effects | |------|------|--------------| | pre_execution.run_pre_execution | Before Step 1 | Detects language, allocates run_id, emits harness_started | | state_sync.StateStore.snapshot | After each specialist | Persists intermediate state to .pgsa/state/.json | | event_emitter.EventBus.emit | Throughout | Pub/sub for telemetry + log subscribers | | post_execution.run_post_execution | After Step 7 | Audits the report (disclosure present, language matches, evidence markers exist) |

Hooks may be subscribers (via EventBus.subscribe) or call-site invoked (via run_pre_execution, run_post_execution). Both styles must adhere to the no-raise-into-harness rule.

12. Extending the Harness — Checklist

• [ ] New skill registered via skills/.md with full frontmatter.
• [ ] Schema exists at assets/schemas/-schema.json OR the skill

reuses an existing one (state which).

• [ ] python -m tools.skill_registry reports zero issues.
• [ ] python -m scripts.setup_local reports zero required-check failures.
• [ ] Tests added under tests/ covering the new behaviour.
• [ ] PROJECT-DEVELOPMENT-PHASE-TRACKING.md updated to reflect the change.

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/private-game-server-automation-agent-skill
• License: MIT

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