# skill-generalizer

Adopt this skill: https://proskills.md/skills/other/hqhq1025-skill-optimizer-skills-skill-generalizer

Page: https://proskills.md/skills/other/hqhq1025-skill-optimizer-skills-skill-generalizer
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/skill-generalizer/SKILL.md
size: 2564
upstream: https://github.com/hqhq1025/skill-optimizer/blob/main/skills/skill-generalizer/SKILL.md

```text
---
name: skill-generalizer
description: Use when turning local, private, or personal Agent Skills into publishable skills for GitHub, marketplaces, teams, or public sharing, especially when private paths, personal habits, credentials, internal hosts, or user-specific context must be removed.
---

# Skill Generalizer

## Overview

Convert a working local skill into a clean public artifact. The goal is to preserve the reusable technique while removing private context, personal assumptions, and machine-specific setup.

## When To Use

- A user wants to publish, share, promote, open-source, or package a local skill.
- A skill was born from personal workflows, private repos, local paths, transcripts, remote hosts, or team conventions.
- The output needs to be useful to strangers without leaking the author's environment.

Do not use for tuning a skill only for the user's own machine; use `skill-personalizer` for that.

## Workflow

1. Inspect the actual source skill and nearby repo files before judging.
2. If the source skill quality is unclear, run the audit checks from `skill-personalizer` first.
3. Separate the reusable capability from personal implementation details.
4. Redact or replace private names, paths, hosts, credentials, account IDs, transcripts, and one-off project facts.
5. Rewrite the skill around general triggering conditions, portable workflows, and bounded assumptions.
6. Keep `SKILL.md` concise; move long rubrics, examples, or scripts into bundled resources.
7. Check target-agent compatibility before writing install instructions or support claims.
8. Produce publication-ready packaging and honest promotion copy only when requested.
9. Verify frontmatter, file layout, install path, and at least one realistic usage prompt.

## Public Release Rules

- Frontmatter `description` should describe when to use the skill, not summarize its workflow.
- Public examples must be generic or explicitly sanitized.
- Claims in README or marketplace copy must match files that actually exist.
- Prefer portable commands and path placeholders over the author's home directory or private aliases.
- If a personal detail is essential, turn it into a configurable variable with setup guidance.

## References

Read [publication-rubric.md](references/publication-rubric.md) when doing a full release pass, redaction review, README rewrite, or promotional packaging.

Read [platform-compatibility.md](references/platform-compatibility.md) before claiming support for Codex, Claude Code, Cursor, OpenCode, Gemini CLI, or other coding agents.
```

## File: README.md
upstream: https://github.com/hqhq1025/skill-optimizer/blob/main/README.md

````text
# Skill Optimizer

[中文版](./README.zh-CN.md)

Three Agent Skills for turning coding-agent work into better `SKILL.md` files:

- **skill-miner** — mine coding-agent history, archives, memories, and repeated work to surface skill-worthy workflows with evidence.
- **skill-personalizer** — audit and adapt newly created, downloaded, forked, or community skills to one user's own tools, habits, directories, and session history.
- **skill-generalizer** — turn local, private, personal skills into publishable skills for GitHub, marketplaces, teams, or public sharing.

Current release: **v2.0.0**. This is a major redesign from the original single-skill optimizer.

Project site: https://hqhq1025.github.io/skill-optimizer/

The split is intentional. Generating, personalizing, and publishing skills are different jobs:

| Goal | Skill | Optimization Direction |
| --- | --- | --- |
| Mine repeated workflows | `skill-miner` | Scan real agent usage, cluster repeated workflows, and draft evidence-backed candidate skills. |
| Fit inward | `skill-personalizer` | Preserve the original optimizer's audit checks, then add local defaults, user phrasing, preferred tools, verification habits, and workflow shortcuts. |
| Publish outward | `skill-generalizer` | Remove private context, generalize examples, make install and README claims portable. |

See [Research Background](./docs/research-background.md) for related agent-skill ecosystems, comparable projects, and papers that motivate session mining, skill libraries, trigger auditing, progressive disclosure, and lifecycle governance.

## Installation

Copy the command below into your agent's chat:

### Claude Code

```text
Install the skills from https://github.com/hqhq1025/skill-optimizer
```

### Codex

```text
Install the skills from https://github.com/hqhq1025/skill-optimizer into ~/.codex/skills/
```

### Other Agent Skills-compatible agents

```text
Install the skills from https://github.com/hqhq1025/skill-optimizer into ~/.agents/skills/
```

Manual install:

```bash
git clone https://github.com/hqhq1025/skill-optimizer.git /tmp/skill-optimizer
mkdir -p ~/.agents/skills
cp -r /tmp/skill-optimizer/skills/skill-miner ~/.agents/skills/
cp -r /tmp/skill-optimizer/skills/skill-personalizer ~/.agents/skills/
cp -r /tmp/skill-optimizer/skills/skill-generalizer ~/.agents/skills/
rm -rf /tmp/skill-optimizer
```

For Codex-only installs, use `~/.codex/skills/`:

```bash
git clone https://github.com/hqhq1025/skill-optimizer.git /tmp/skill-optimizer
mkdir -p ~/.codex/skills
cp -r /tmp/skill-optimizer/skills/skill-generalizer ~/.codex/skills/
cp -r /tmp/skill-optimizer/skills/skill-miner ~/.codex/skills/
cp -r /tmp/skill-optimizer/skills/skill-personalizer ~/.codex/skills/
rm -rf /tmp/skill-optimizer
```

For Claude Code-only installs, use `~/.claude/skills/`.

## Platform Support

| Agent | Support level | Recommended path |
| --- | --- | --- |
| Codex | Native Agent Skills, plus optional plugin metadata. | `~/.codex/skills/` or `.agents/skills/` |
| Claude Code | Native skills in personal, project, and plugin scopes. | `~/.claude/skills/` or `.claude/skills/` |
| Cursor | Native Agent Skills and rules/commands; skills are discoverable by Agent. | `.agents/skills/`, `.cursor/skills/`, or global skills |
| OpenCode | Native `skill` tool and repo/home skill discovery. | `.agents/skills/`, `.opencode/skills/`, or `~/.config/opencode/skills/` |
| Gemini CLI / Google agents | Agent Skills open format is documented by Google; `GEMINI.md` remains the always-on context mechanism. | `.agents/skills/` or installer-managed skills |

The safest public layout is `skills/<name>/SKILL.md` in the repo plus install instructions that copy into `.agents/skills/` or the target agent's native skill directory.

## Usage

Ask for the direction you want:

```text
Mine my coding-agent history and find repeated workflows that should become skills.
```

```text
Audit and tune my installed skills; tell me which ones are undertriggering, too noisy, or too generic.
```

```text
Turn this local skill into a public GitHub-ready skill.
```

```text
I downloaded this skill. Tune it to my local workflow and usage habits.
```

```text
This skill does not trigger when I say things naturally. Personalize it for me.
```

## What Each Skill Does

### skill-miner

- coding-agent session history, memory summaries, repo notes, repeated scripts, and project folders
- recurring user intents, shorthand, tool chains, artifacts, and verification patterns
- candidates that are repeated and non-obvious enough to become skills
- whether a candidate should stay personal, be generalized for publication, or be skipped
- includes `scripts/scan_sessions.py` for a deterministic first-pass scan of Codex, Claude Code, Gemini/Antigravity task files, and exported transcripts from other agents
- includes archived Codex sessions and rollout summaries by default, with flags to disable archive/summary sources

Example:

```bash
python3 skills/skill-miner/scripts/scan_sessions.py --days 30 --limit 300 --min-count 3
python3 skills/skill-miner/scripts/scan_sessions.py --export ~/Downloads/cursor-chat-export.json
python3 skills/skill-miner/scripts/scan_sessions.py --patterns ./my-patterns.json
python3 skills/skill-miner/scripts/scan_sessions.py --no-include-archives --no-include-summaries
```

### skill-generalizer

- private paths, hosts, credentials, account names, transcript quotes, and internal repo facts
- public portability of commands, examples, README claims, and install instructions
- frontmatter that describes when to use the skill rather than the workflow
- packaging structure for public distribution

### skill-personalizer

- local installed copies and nearby project instructions
- real user phrasing and recurring task patterns
- preferred CLIs, MCP tools, paths, aliases, and verification commands
- undertrigger, overtrigger, and unnecessary-question friction
- original optimizer-style audit checks: trigger fit, user reaction, workflow completion, static quality, conflicts, environment consistency, token economics, and P0/P1/P2 fixes

## Compatibility

Works with agents that support the Agent Skills folder convention:

- Claude Code
- Codex
- Cursor
- OpenCode
- Gemini CLI

## Research Background

This project is informed by Agent Skills ecosystem work and LLM-agent research on externalized memory, skill libraries, retrieval/routing, and long-context behavior. See [docs/research-background.md](./docs/research-background.md).

## AI And Search Visibility

- Project site: https://hqhq1025.github.io/skill-optimizer/
- LLM summary: [llms.txt](./llms.txt)
- Full LLM context: [llms-full.txt](./llms-full.txt)
- Structured metadata: [repo-metadata.json](./repo-metadata.json)

## License

MIT
````
