Contribute a SkillCred Sandbox Item

You will contribute one scored sandbox item that fits the assigned blueprint competency and passes the local sandbox test.

What you will contribute

You will leave one item ready for review.

Artifact	Outcome
task.en.md	Presents the candidate task.
host1/scripts/build.sh	Builds the VM starting state.
host1/scripts/setup.sh	Prepares runtime state.
host1/scripts/answer.sh	Proves the task can be solved.
host1/scripts/score.sh	Scores the candidate end state.
metadata.yaml	Places the item in the SkillCred plan.

The local proof is:

sandbox build && sandbox test

Who this guide is for

Use this guide when Global Skills assigns you a sandbox item in a SkillCred repository.

You bring domain knowledge. The platform docs teach the repository and sandbox workflow.

Before you start

You need three things before you begin:

• GitHub access to the SkillCred repository.
• Codespaces access.
• An item assignment from Global Skills.

Note

Use Setting Up for Codespaces, Devbox, and tool checks.

Work on a branch. Do not work directly on main.

Work happens inside the assigned item directory. Changes to blueprint.yaml, existing item names, shared repository configuration, or other items flow through Global Skills.

Ready to start

You understand the assigned competency, the assigned difficulty, the surrounding items, and your developer environment.

Understand the SkillCred assignment

You will use blueprint.yaml as the source of truth for the SkillCred.

A SkillCred measures whether a candidate has the minimum skills needed for the job role behind the exam. The candidate is minimally qualified in the blueprint domain. The candidate is not assumed to be an expert.

Read the full blueprint before you write the item. The full blueprint shows the boundaries between competencies.

Read existing items in items/. Existing items show current task style, scoring techniques, and lifecycle script patterns.

Your assignment gives you:

• The item directory or item name.
• The competency to test.
• The difficulty tier.

Each item tests one competency. Keep the main task and scoring focused on that competency. The scenario can require related skills, but the item evaluates the assigned competency.

Difficulty tiers

Treat difficulty as a platform timing tier.

Tier	Estimated time to solve
easy	About 2 minutes.
medium	About 4 minutes.
hard	About 6.5 minutes.

If your scenario feels similar to an existing item, or the competency boundary is unclear, contact Global Skills.

Prepare your environment

You will prepare the repository Codespace with the standard setup guide.

Follow Setting Up before you edit the assigned item.

Tip

Complete the Quickstart first when the sandbox CLI is new to you.

Create your branch

You will isolate the item work on an implementation branch.

Create a branch before you scaffold or edit an item.

@codespace-author ➜ .../SCXXX-Exam (main)

git switch -c implement/<item-name>

You now have a branch for your item work.

Enter or scaffold the item

You will work in the item directory that contains the sandbox files.

A sandbox is a hands-on environment where a candidate must actually do something to pass.

Assigned item New item

Enter the directory Global Skills assigned to you.

@codespace-author ➜ .../SCXXX-Exam (implement/<item-name>)

cd items/<item-name>

You now have the item files in your working directory.

Run the initializer from items/ when no item directory exists.

@codespace-author ➜ .../SCXXX-Exam (implement/<item-name>)

cd items
sandbox init

Select Exam task → name it with the next available item name → accept all other defaults → Create → validate.

You now have a scaffolded SkillCred item.

Use the Quickstart when you need a full sandbox init walkthrough.

Write the candidate task

You will write the prompt the candidate reads during the exam.

Edit task.en.md.

State the required outcome. Include only the context the candidate needs to act.

Write a task that reflects a common real-world scenario. Avoid hyper-specific edge cases. Avoid forcing one exact path when multiple valid tools or commands can produce the required end state.

The task must not award free points. The candidate must do work to pass.

Match the SC10x voice and style: see Task style and voice for the canonical skeleton, admonition vocabulary, and scoring boilerplate.

Checkpoint

You have a candidate-facing task prompt.

Build the starting state and scoring

You will create the starting VM state, the reference answer, and the scoring checks.

The sandbox lifecycle scripts own build, runtime setup, answer, and scoring behavior.

Lifecycle map

Script	Purpose
build.sh	Bakes packages, tools, files, and static assets into the VM image.
setup.sh	Waits for runtime readiness when necessary; left blank when possible.
answer.sh	Simulates a correct candidate.
score.sh	Grades the candidate end state.

Put files and tools mentioned in the task into the VM before the candidate starts.

Use build.sh for image-time setup, including enabling services with systemctl enable --now. Leave setup.sh blank unless the sandbox has a known startup delay that outlasts SSH availability — Kubernetes cluster readiness is the canonical case.

Write answer.sh as candidate-like shell actions. Use the same tools available to the candidate. Do not hide the solution inside complex scripting.

Put waits for services or eventual state in setup.sh or score.sh, not answer.sh. Only add waits in setup.sh when they are necessary — do not add them as a precaution.

Write score.sh to measure the end state. Focus the checks on the assigned competency. End the script with scoring::report.

Use the sandbox reference when you need details on sandbox.yaml, tools, lifecycle scripts, or CLI commands.

When you need several terminals or are editing multiple VMs, use the background development workflow with CLI v1.27+. Each started VM watches its scripts, assets, and local library dependencies. Separate sandbox attach terminals do not own the VM lifecycle, and a library-only edit can regenerate an unchanged lifecycle script.

Use the Bashp MCP tools to inspect helper implementations and resolve dependencies. A resolution pass does not prove that the candidate task, reference answer, or scoring behavior is correct.

Checkpoint

You have a VM starting state, a reference answer, and scoring logic.

Add item metadata

You will declare how the item fits the SkillCred plan.

Edit metadata.yaml.

Set the assigned competency, assigned difficulty, item title, revision, and total check count.

Make total_check_count match the combined number of scoring::check and scoring::namedcheck registrations in score.sh.

Keep metadata focused on the item. Do not add legacy or unrelated fields.

Checkpoint

You have metadata that matches the assigned competency, difficulty, and scoring checks.

Test the item locally

You will prove the item starts, withholds points before candidate work, and awards full points after the reference answer.

Exit any owning development shell, or stop background VMs with sandbox stop, before acceptance testing. Run the local test from the item directory; it uses a fresh owned VM session without live reload.

@codespace-author ➜ .../items/<item-name> (implement/<item-name>)

sandbox build && sandbox test

You now know the sandbox build and lifecycle test pass locally.

sandbox test verifies two required outcomes:

• Untouched sandbox

The sandbox earns zero checks before candidate work.

• Reference answer

The answer script earns every check.

Fix failures before you mark the pull request ready for review.

Open a pull request

You will share your item work for review.

Push your branch often.

@codespace-author ➜ .../SCXXX-Exam (implement/<item-name>)

git push -u origin implement/<item-name>

You now have a remote branch for review and backup.

Open a draft pull request when you need feedback or help before the item is complete.

Mark the pull request ready for review after the task, lifecycle scripts, metadata, and local sandbox test are complete.

Respond to review feedback

You will update the item until it is ready to merge.

Use review feedback to clarify the task, tighten scoring, adjust the starting state, or align the item with the assigned competency.

Keep each change inside the item directory unless the reviewer asks for a repository-level change.

Push updates to the same branch.

Done checklist

You are done when

• task.en.md contains the candidate-facing prompt.
• build.sh, setup.sh, answer.sh, and score.sh exist.
• The initial VM state contains every tool, file, and asset named in the task.
• Runtime readiness lives in setup.sh.
• answer.sh uses candidate-available tools and earns full points.
• score.sh focuses on the assigned competency.
• score.sh ends with scoring::report.
• metadata.yaml contains the assigned competency and difficulty.
• metadata.yaml has a total_check_count that matches score.sh.
• sandbox build && sandbox test passes.
• The untouched sandbox earns zero checks.
• The reference answer earns every check.
• You did not edit blueprint.yaml.
• You did not modify files outside your item directory.

Where to go next

• Setting Up

Prepare Codespaces, Devbox, skills, and sandbox.

• Quickstart

Practice the sandbox CLI before working on an assigned item.

• Sandbox reference

Look up sandbox.yaml, tools, lifecycle scripts, and CLI commands.