Start a fresh conversation. Replace the highlighted placeholders.
Use gentle-ai-skill-improver to apply [explicit improvement plan] to [named SKILL.md path]. Read docs/skill-style-guide.md and the registry if available, preserve author intent, critical rules, activation and output requirements, and apply only safe requested fixes. Move meaningful long examples or rationale to local assets/references rather than deleting them. Flag conflicts or unclear rules for human review. Return exact paths, issues by severity, changed files, verification results, and any registry refresh recommendation; preserve a backup before editing.
Required inputs
[explicit improvement plan]
[named SKILL.md path]
User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗
Use this skill when auditing, refactoring, normalizing, or improving existing SKILL.md files. Use gentle-ai-skill-creator when creating a brand-new skill from a reusable pattern.
Hard Rules
Read docs/skill-style-guide.md first and treat it as the normative style contract.
Treat SKILL.md as the source of truth; preserve author intent, critical rules, activation semantics, and output requirements.
Use .atl/skill-registry.md as an index of skill names, triggers, scopes, and exact paths when available.
Default to audit-only. Modify files only when the user explicitly asks to apply improvements.
Never delete meaningful content silently; move long explanation, examples, templates, or schemas into local references/ or assets/.
Do not invent triggers, policies, or domain rules. Mark ambiguous cases for human review.
Decision Gates
Situation
Action
Missing or invalid frontmatter
Fix name, quoted one-line description, license, and metadata
Skill reads like tutorial docs
Convert to runtime instructions and move background to references/
Body exceeds budget
Preserve rules, move examples/background to supporting files
Branching logic hidden in prose
Convert to a compact decision table
Rules conflict or intent is unclear
Report the issue; do not rewrite that rule automatically
Execution Steps
Read docs/skill-style-guide.md.
Read .atl/skill-registry.md; use listed paths to select skills. If missing, scan known skill directories for */SKILL.md.
For each selected skill, audit metadata, trigger clarity, section order, body budget, actionability, decision gates, output contract, and local references.
Return an audit report grouped by skill with severity and exact proposed changes.
In apply mode, edit only safe issues, preserve content, create supporting files when needed, then refresh or request /skill-registry:refresh.
Output Contract
Return:
Skills audited and paths used.
Issues found, grouped by severity.
Files changed, if apply mode was requested.
Registry refresh recommendation when skill metadata or paths changed.