---
title: "Structural Analysis"
description: "How selftune inspects skill structure and cloud compatibility"
---
## Overview
When selftune runs a cloud improve pass, it performs a structural analysis of each skill before generating candidates. This analysis checks that the skill is well-formed for cloud execution and flags issues that could affect quality or compatibility.
Structural analysis results appear in improve run details and drive the recommendations shown in the dashboard.
## Frontmatter analysis
selftune reads two frontmatter fields to understand how a skill is configured:
| Field | What it checks |
|-------|---------------|
| `compatibility` | Whether the skill declares cloud compatibility or incompatibility |
| `allowedTools` | The list of tools the skill is permitted to use |
If `compatibility` is set to a value that signals cloud incompatibility, the skill will receive a `review_compatibility_contract` recommendation. If `allowedTools` is missing or misconfigured for cloud use, a `review_allowed_tools_contract` recommendation is raised.
## Execution analysis
selftune analyzes the skill body to infer how it runs at execution time:
| Signal | Description |
|--------|-------------|
| `needsExternalSecrets` | Skill references environment variables or secrets |
| `needsArbitraryShell` | Skill invokes shell commands beyond standard tool use |
| `needsLocalFilesystemContext` | Skill depends on local file paths or project state |
| `declaresCloudIncompatibility` | Skill explicitly opts out of cloud execution |
| `supportsCloudWriteback` | Skill is configured to write results back via cloud |
Skills that depend on local filesystem context or external secrets may not run correctly in cloud improve without additional configuration.
## Script strategy
Each skill is assigned a script strategy based on how it uses the `Scripts/` directory:
| Strategy | Meaning |
|----------|---------|
| `no_script_needed` | Skill does not require a script |
| `prefer_existing_tool` | A built-in tool covers the use case; no script needed |
| `bundle_script_candidate` | Skill could benefit from a bundled script |
| `script_present` | A script exists and appears healthy |
| `script_present_but_low_quality` | A script exists but has quality issues |
The script quality issue count is reported alongside the strategy so you can prioritize fixes.
## Recommendation codes
Structural analysis can produce the following recommendations:
| Code | Severity | What to do |
|------|----------|------------|
| `harden_script_ergonomics` | warning | Improve error handling and output formatting in your script |
| `prefer_existing_tool` | info | Replace the script with a native tool call |
| `consider_bundled_script` | info | Add a script to `Scripts/` to support this skill's use case |
| `reduce_skill_md_size` | warning | Trim SKILL.md — large files increase token usage and reduce improve quality |
| `review_compatibility_contract` | warning | Check the `compatibility` frontmatter field for accuracy |
| `review_allowed_tools_contract` | warning | Review and update the `allowedTools` frontmatter declaration |
| `review_scripts_directory` | warning | Scripts directory has structural issues |
| `split_skill_scope` | warning | Skill covers too many use cases — consider splitting |
| `review_cloud_limitations` | info | Skill uses features that may not behave identically in cloud |
| `contain_file_references` | warning | Skill contains cross-package filesystem links that escape the skill directory |
### File reference containment
Skills that reference sibling skill packages using relative filesystem paths (for example, `../other-skill/SKILL.md`) cannot be reliably uploaded as self-contained packages. When selftune detects these escaping links, it raises a `contain_file_references` recommendation.
The cloud improve runner addresses this automatically by generating a structural candidate that:
- Replaces relative filesystem links with plain skill-name references (`` `other-skill` ``)
- Adds a **Related Skills** section that documents how to load sibling skills independently
The resulting package stays self-contained without losing the cross-skill relationship information.
## Skill size
selftune tracks both line count and a token estimate for each skill file. Skills that exceed recommended size limits receive a `reduce_skill_md_size` recommendation. Keeping SKILL.md concise improves improve run quality and reduces cost.
## Viewing results
Structural analysis results are shown in the improve run detail view on the dashboard. Recommendations appear with their severity and a short description to guide next steps.
See [improve run statuses](/cloud/improve-run-statuses) for how structural analysis fits into the overall improve run lifecycle.
