Gentle AI Skill Improver Agent Skill

Activation Contract

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.
• Ambiguities that need human review.

References

• docs/skill-style-guide.md — normative LLM-first skill style guide.
• skills/skill-registry/SKILL.md — registry refresh and indexing contract.