skill-improver

Name: skill-improver
Author: Gentleman-Programming

Security Community

Repo stars 3,249
License Apache-2.0
Author repo gentle-ai

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Trigger: improve skills, audit skills, refactor skills, skill quality. Audit and upgrade existing LLM-first skills. Use this ski…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Activation Contract”, “Hard Rules”, “Decision Gates”, “Execution Steps”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name skill-improver directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Activation Contract / Hard Rules / Decision Gates” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Activation Contract

Use this skill when asked to audit, refactor, normalize, or improve existing SKILL.md files. Use skill-creator instead when creating a brand-new skill from a reusable pattern.

Hard Rules

Treat docs/skill-style-guide.md as the normative style contract when it exists.
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; do not expect generated summaries.
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; if unavailable, enforce the core LLM-first structure: frontmatter, Activation Contract, Hard Rules, Decision Gates, Execution Steps, Output Contract, References.
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 rerun or request gentle-ai 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 for this repo.

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Security
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 94 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @Gentleman-Programming · Apache-2.0
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Shell exec
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview skill-improver-gentleman-programming.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

## Activation Contract

Use this skill when asked to audit, refactor, normalize, or improve existing `SKILL.md` files. Use `skill-creator` instead when creating a brand-new skill from a reusable pattern.

## Hard Rules

- Treat `docs/skill-style-guide.md` as the normative style contract when it exists.
- 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; do not expect generated summaries.
- 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`; if unavailable, enforce the core LLM-first structure: frontmatter, Activation Contract, Hard Rules, Decision Gates, Execution Steps, Output Contract, References.
2. Read `.atl/skill-registry.md`; use listed paths to select skills. If missing, scan known skill directories for `*/SKILL.md`.

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Activation Contract → Hard Rules → Decision Gates → Execution Steps → Output Contract → References
terms    -> Use this skill when asked to audit, refactor, normalize, or improve existing SKILL.md files. · - Treat docs/skill-style-guide.md as the normative style contract when it exists. · Return: - Skills audited and paths used. · - docs/skill-style-guide.md — normative LLM-first skill style guide for this repo.
files/cmd -> skill-creator · docs/skill-style-guide.md · .atl/skill-registry.md · references/ · assets/ · name · description · license
body sha256 -> 6f4e6ee425a5