Sandbox Custom Challenge Rules Agent Skill

SKILL.md — Skill Registry & Operations Manual

> Audience: developers integrating this skill into a Claude Code or > Claude-equivalent environment, and operators running the harness headlessly > via scripts/run_harness.py. > > Scope: how skills are registered, resolved, executed, validated, and > how the harness enforces quality gates.

---

1. Skill Registry

Every skill is a markdown file under skills/. The file name (without .md) is the skill identifier. The harness discovers skills by listing this directory at startup; there is no separate registry file to maintain.

| File | Tier | Role | |------|------|------| | skills/main.md | — | Router + quality gate enforcer | | skills/sub-gather-requirements.md | 1 | Intake | | skills/sub-evidence-collector.md | 1 | Evidence gathering | | skills/sub-knowledge-updater.md | 1 | Knowledge brain queries | | skills/sub-game-classifier.md | 1 | Game/genre classification + router decision | | skills/sub-constraint-designer.md | 2 | Constraint set design | | skills/sub-balance-tuner.md | 2 | Difficulty curve + flow analysis | | skills/sub-enforcement-engineer.md | 2 | Enforcement mechanism specification | | skills/sub-replayability-analyst.md | 2 | Emergence + replay fatigue | | skills/sub-advisor.md | 3 | Synthesis + verdict + disclosure |

1.1 Frontmatter Contract

Every skills/*.md MUST start with this exact frontmatter shape:

---
name: 
description: 
---

• name MUST match the file stem.
• description is the trigger surface. It should describe both what the

skill does AND when to use it. Mention concrete verbs (design, balance, audit) and concrete games (Minecraft, RimWorld).

• No other frontmatter fields are required.

1.2 Section Contract

After frontmatter, each sub-skill MUST include these sections in order:

1. ## Role & Persona
2. ## Workflow
3. ## Tools
4. ## Output Format
5. ## Quality Gates

skills/main.md additionally includes:

• ## Sub-skills Available
• ## Graceful Degradation
• ## Error Recovery
• ## Output Format (the full report template)

---

2. Skill Resolution

When a user invokes /sandbox-custom-challenge-rules, the host (Claude Code or another LLM harness) resolves the skill as follows:

1. Match the slash command to skills/main.md (registry lookup).
2. Load main.md into context.
3. Read references/gate_matrix.md for the gate spec.
4. Read config/skill_config.py for runtime configuration.
5. Begin executing the Harness Execution Protocol in main.md.

Sub-skills are resolved on demand via Skill(""). The host loads the corresponding skills/sub-*.md and continues execution.

2.1 Resolution Edge Cases

| Case | Behavior | |------|----------| | Sub-skill file missing | Harness fails fast with Skill not found: . | | Sub-skill file present but no frontmatter | Harness warns, treats the file body as the skill. | | Circular sub-skill invocation | Harness detects depth > 4 and aborts with a cycle error. | | Unknown game_family | sub-game-classifier escalates to the user; harness waits. |

---

3. Skill Execution

3.1 Tiered Execution Model

main.md (Tier-0 router)
  ↓
Tier-1 (sequential, must complete in order):
  sub-gather-requirements → sub-evidence-collector →
  sub-knowledge-updater   → sub-game-classifier
  ↓
Tier-2 (parallelizable within tier, but constraint_designer must complete first):
  sub-constraint-designer (mandatory first)
  sub-balance-tuner       (depends on constraints)
  sub-enforcement-engineer(depends on constraints)
  sub-replayability-analyst(depends on constraints + difficulty_curve)
  ↓
Tier-3 (single sub-skill):
  sub-advisor
  ↓
main.md (quality gate review)

3.2 Input/Output Contracts

Every sub-skill publishes its input and output schema fragment. The full state object is defined in assets/schemas/harness_state.schema.json. Each sub-skill:

• reads keys produced by upstream steps (declared in its Workflow Step 1).
• writes a single top-level key (declared in its Output Format).

| Sub-skill | Reads | Writes | |-----------|-------|--------| | sub-gather-requirements | user input | requirements | | sub-evidence-collector | requirements | evidence_bundle | | sub-knowledge-updater | requirements, evidence_bundle | knowledge_citations | | sub-game-classifier | requirements, evidence_bundle | classification | | sub-constraint-designer | requirements, classification, evidence_bundle | design_draft.constraints | | sub-balance-tuner | classification, design_draft.constraints | design_draft.difficulty_curve | | sub-enforcement-engineer | classification, design_draft.constraints | design_draft.enforcement | | sub-replayability-analyst | design_draft.constraints, design_draft.difficulty_curve | design_draft.replayability, design_draft.scenarios | | sub-advisor | full state | synthesis + final report |

3.3 Hook Integration

Every phase boundary fires a hook from hooks/harness_hooks.py. Hooks emit events to logs/hooks.log and persist run state to logs/runs/.json.

The hook contract (return shape) is documented in hooks/harness_hooks.py. Hooks MUST NOT raise; failures are logged and downgraded.

3.4 Headless Execution

For CI / batch runs, use scripts/run_harness.py:

python scripts/run_harness.py \
    --user-input "design a hardcore skyblock Minecraft challenge" \
    --language en \
    --dry-run

In --dry-run mode, the runner uses an offline classifier and a placeholder constraint skeleton. It exercises every hook, validates state against the schema, and writes the run state to disk. Useful for smoke-testing the plumbing without spending LLM tokens.

Without --dry-run, the runner expects to be driven by an LLM agent that reads skills/main.md and dispatches sub-skills per its instructions. The runner then provides the schema-validated state object the agent writes to.

---

4. Skill Validation

The project ships three validators. Run them in this order:

4.1 8-File Contract: tools/validate_project.py

Checks file presence, frontmatter, section headings, UTF-8 encoding, placeholder-free content, cross-file references, knowledge-brain structure.

python tools/validate_project.py

Exit code 0 = pass.

4.2 Structural / Content: tools/run_test_scenarios.py

Checks sub-skill count, gate coverage, knowledge-brain tier labels, DOI counts, scenario coverage.

python tools/run_test_scenarios.py

4.3 Knowledge Updater Unit Tests: tools/test_knowledge_updater.py

python tools/test_knowledge_updater.py

4.4 Schema Validation (new)

The runner validates every emitted state against assets/schemas/harness_state.schema.json (which references assets/schemas/challenge_design.schema.json). To validate a captured state file:

python scripts/run_harness.py --validate-only logs/runs/run-XYZ.json

4.5 Hooks Smoke Test

python hooks/harness_hooks.py

Exercises every hook with sample inputs.

4.6 Setup Self-Check

python scripts/setup_env.py
python scripts/setup_env.py --fix

Verifies Python version, dependencies, directories, and critical files.

---

5. Configuration Surface

Configuration is centralized in config/skill_config.py and surfaced as immutable dataclasses. Override paths (highest precedence first):

1. Environment variables (SCCR_*).
2. config/config.yaml or config/config.json (project override).
3. Dataclass defaults in config/skill_config.py.

To inspect the resolved config:

python -m config.skill_config            # human-readable
python -m config.skill_config --json     # machine-readable

Key configuration surfaces:

| Section | What it controls | |---------|-----------------| | llm | model id, temperature, max tokens, retries, timeout | | knowledge | brain path, cron schedule, crawl budgets | | harness | language default, gate retry max, degradation floor | | flags | per-game and per-mode feature gates | | logging | log level, directory, rotation |

---

6. Adding a New Sub-Skill

To add a new specialist (e.g. sub-accessibility-auditor):

1. Create skills/sub-accessibility-auditor.md with the frontmatter + 5 required sections.
2. Add it to the ## Sub-skills Available table in skills/main.md.
3. Add a row to the I/O contract table in this file (Section 3.2).
4. If it produces a new fragment, add the sub-schema to assets/schemas/challenge_design.schema.json.
5. Update tools/validate_project.py and tools/run_test_scenarios.py if the 8-File Contract or scenario coverage must change.
6. Document the addition in CHANGELOG.md.
7. Re-run all four validators.

The classifier in skills/sub-game-classifier.md is the only place that decides which Tier-2 specialists to invoke; update it to emit the new specialist when appropriate.

---

7. Versioning & Compatibility

This file documents registry/execution contract version 1.0.0, matching the schema_version field in assets/schemas/challenge_design.schema.json.

Breaking changes (frontmatter shape, sub-skill count, schema version) require a minor-version bump in progression.json and a CHANGELOG.md entry. Non-breaking additions (new feature flag, new specialist) require a patch bump.

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/sandbox-custom-challenge-rules-agent-skill
• License: MIT

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