Gentleman-Programming/gentle-shell / skills/skill-improver
gentle-ai-skill-improver
VerifiedTrigger: improve skills, audit skills, refactor skills, skill quality. Audit and upgrade existing LLM-first skills.
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.mdfirst and treat it as the normative style contract. - Treat
SKILL.mdas the source of truth; preserve author intent, critical rules, activation semantics, and output requirements. - In Pi use the effective session skill view for names, triggers, scopes, and exact paths. The shared
.atl/skill-registry.mdis a disk-only fallback and omits runtime-only skills. - 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/orassets/. - 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. - Use the effective session view (
<available_skills>plus anyEffective session skillsrows) to select skills. If neither is present, report that limitation and use.atl/skill-registry.mdas a disk-only fallback; if absent, 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |