Troubleshooting
Diagnose package validation, ownership, version and consumption problems
Start with the failed stage: opening, parsing, creating, saving, activating, consuming or removing. Keep the workspace, skill/source, version and exact error so you do not confuse an unsaved draft with a persisted asset.
| Symptom | Check | Next action |
|---|---|---|
| Create controls unavailable | Workspace selection and membership | Select the accessible workspace/project |
| Missing frontmatter | SKILL.md starts with bounded YAML delimiters | Add name and description followed by useful Markdown |
| Empty or invalid head | Name, description and nonempty body | Correct the head before saving |
| ZIP has no root head | Common directory and actual file paths | Put SKILL.md at the imported package root |
| Referenced checklist missing | Files actually imported | Add it or use the complete ZIP/JSON package |
| File/package too large | UTF-8 byte totals | Reduce text; limits are 256 KiB per file and 1 MiB total |
| Agent reports a taken name | Existing standalone and plugin names | Edit the existing asset or choose a unique new name |
| Plugin skill cannot save/branch/activate | source plugin and readOnly true | Use its parent plugin lifecycle or an independent copy |
| Historical view cannot edit | Version view is read-only | Edit the current standalone package or activate a reviewed revision |
| Save changed shared behavior | New saved revision becomes active by default | Compare files and restore the reviewed older version if needed |
| Skill has no apparent effect | Consumer context, actual text, file loading and revision | Verify consumption or provide the instructions explicitly |
| Skill node does not execute | No default skill execution tool | Use a supported authoring/review context or a real executable capability |
| Deletion fails | Dependencies, actor permissions and source | Resolve references; plugin skills belong to their parent |
A reproducible guidance failure
Use a fixed fixture such as pump-17 with probability 0.70, evidence cutoff 1 October 2026 at 12:00 UTC, observation 2 October at 09:00 UTC and no supplied outcome. Supply the actual instructions and record which package version they came from.
A review that calls the later observation an original input has missed the timing rule. A review that claims failure occurred has confused probability with outcome. Before changing the package, confirm that the task received the intended text and supporting files.
A creation failure
A draft, validation result and final create action are separate records. Check the specific artifact revision and current validation. If deployment approval configuration disables the final action, manual creation or upload remains a separate supported path; do not report the draft as installed.
Report the evidence
Include workspace/project identifiers, standalone versus plugin source, asset/capability and version IDs, expected versus actual result, safe validation text and whether any save/delete action succeeded. Exclude credentials and private source records. See Getting help.