Skip to content

debugging.md

Latest commit

 

History

History
54 lines (38 loc) · 3.86 KB

debugging.md

File metadata and controls

54 lines (38 loc) · 3.86 KB
Raw

Debug Skills locally

Use a mature agent such as Codex or Claude Code for Skill development. The host provides model access, tools and conversation management. Other compatible agents, including 豆包工作, can use their own Skill installation flow; dedicated setup instructions here cover Codex and Claude Code.

Create a workspace

Start from this repository's root. Keep each experiment in its own ignored .cache/skill-dev/<skill-name>/<run-name>/ directory:

mkdir -p .cache/skill-dev/data-storytelling
debug_workspace="$(mktemp -d "$PWD/.cache/skill-dev/data-storytelling/run.XXXXXX")"
mkdir -p "$debug_workspace/outputs" "$debug_workspace/screenshots" "$debug_workspace/logs"
cp -R cases/data-storytelling/story-retention-html/inputs "$debug_workspace/inputs"
cp cases/data-storytelling/story-retention-html/prompt.md "$debug_workspace/prompt.md"

Only copy the prompt and inputs for generation. Leave the case README's acceptance criteria in the repository for review after the task. For your own task, put its prompt and source files in the same workspace structure.

Choose one host, installed and authenticated. For Codex:

mkdir -p "$debug_workspace/.agents/skills"
cp -R skills/data-storytelling "$debug_workspace/.agents/skills/"
cd "$debug_workspace"
codex

For Claude Code, instead run this from the repository root after the shared setup:

mkdir -p "$debug_workspace/.claude/skills"
cp -R skills/data-storytelling "$debug_workspace/.claude/skills/"
cd "$debug_workspace"
claude

You can open the workspace in the corresponding app. Install the complete Skill, including references, templates and scripts. See the Codex Skill documentation and Claude Code Skill documentation for host-specific discovery.

Ask the agent to use data-storytelling to execute prompt.md, read inputs from inputs/ and write generated files to outputs/. For another Skill, change the Skill name and supply its task and assets. See the root runtime requirements; install any required packages in a local environment under .cache/.

Iterate and keep evidence

  • Edit source instructions and scripts in skills/<skill-name>/. Refresh the installed copy before each retest, or create a fresh workspace. Changing only the installed copy will not update the repository source.
  • Keep fixed inputs in cases/ unchanged during a run. Work on the copied inputs when a task requires transformation.
  • Save generated artifacts under outputs/, screenshots under screenshots/ and available session/tool logs under logs/. Host logs are not collected automatically by this repository; export them where supported and note missing evidence.
  • Use notes.md to record the Skill commit and any local changes, host/model, task outcome, checks, failures and manual review. Keep a Skill snapshot or diff with the run when reproducing an uncommitted version.
  • Open the output in a browser and exercise required interactions. Check the case's acceptance points after generation. A rendered page alone does not establish data or visual correctness.
  • .cache/ is ignored by Git. Keep credentials and private material out of shared reports. Clean only workspaces you own; do not delete another session's files automatically.

Promote reusable task inputs and acceptance criteria to cases/, reviewed showcase results to examples/, and deterministic regressions to tests/. Keep raw logs, draft outputs and experimental screenshots local.

Automated checks

Use the contribution guide to select script regressions and browser smoke. These checks run without a model. Actual task execution and review use your chosen agent; there is no repository model API configuration or batch agent runner.