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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.8 KB |
SKILL.md
View on GitHub---
name: gentle-ai-skill-improver
description: "Trigger: improve skills, audit skills, refactor skills, skill quality. Audit and upgrade existing LLM-first skills."
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.0"
---
## 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.
- In Pi use the effective session skill view for names, triggers, scopes, and exact paths. The shared `.atl/skill-registry.md` is 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/` 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
1. Read `../../docs/skill-style-guide.md`.
2. Use the effective session view (`<available_skills>` plus any `Effective session skills` rows) to select skills. If neither is present, report that limitation and use `.atl/skill-registry.md` as a disk-only fallback; if absent, scan known skill directories for `*/SKILL.md`.
3. For each selected skill, audit metadata, trigger clarity, section order, body budget, actionability, decision gates, output contract, and local references.
4. Return an audit report grouped by skill with severity and exact proposed changes.
5. 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.
- `../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: 472k | 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: 472k | 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: 472k | 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: 194k | Updated | Claude CodeCodex | Verified | Install |