Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Skill Manager?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/axgord-skill-manager)
---
name: skill-manager
description: Create, install, update, optimize skills
---
## Skill lifecycle manager
This skill is HEAVY. Always run via subagent (Task tool), never in main context.
### Model policy
Model AND effort per spawn by the `task-delegation` table. Skill text is
judgement with no mechanical net → sonnet/medium for optimize and create,
opus/high for a skill that decides process; haiku only for locate/extract
helpers whose output you re-check.
### Where a rule lives (JIT over global)
- A rule needed at one process moment (spawning, commit, review) goes into
that moment's carrier — the workflow state prompt or the skill loaded
then — never into a global CLAUDE.md, which keeps only bootstrap,
every-reply rules and facts with no carrier (e.g. git identity).
- Universal tool discipline goes into the distributed carriers (bundled
skills, workflow templates), never into `preferences-*` (personal taste).
- A rule a linter can hold goes into the lint config, not into a skill:
check the project's `hxq lint --list-rules <files>` before writing it.
- What only one route needs (writes, self-development, liveness forensics)
goes into a separate skill or `references/`, not the always-loaded SKILL.md.
### ⛔ PROTECTED skills — NEVER modify or overwrite
Skills matching `preferences*` (`preferences/`, `preferences-<lang>/`,
any other `preferences-*` variant) are user-owned personal rules.
These are ONLY updated when the user gives direct feedback.
skill-manager must NEVER touch, overwrite, or regenerate them without
an explicit user request.
### 1. FIND an existing skill
Search order:
A) Check awesome-agent-skills: https://github.com/VoltAgent/awesome-agent-skills
B) Check awesome-claude-code: https://github.com/hesreallyhim/awesome-claude-code
C) Check anthropics/skills: https://github.com/anthropics/skills
D) Search npm: `npm search claude skill <keyword>`
E) Search GitHub: `gh search repos "claude skill <keyword>"`
**IMPORTANT:** Subagents don't have access to skills. When launching a research subagent, include these web-reading rules in the prompt:
1. For GitHub repos/issues/PRs → use `gh` CLI, not web fetch
2. Fetch web pages via Jina Reader: `WebFetch("https://r.jina.ai/<url>", "<precise extraction prompt>")`
3. If Jina fails → direct `WebFetch` with prompt: "Extract ONLY main article content as clean markdown. Ignore navigation, sidebars, headers, footers, ads."
4. If page inaccessible → `WebSearch` for mirrors, docs, cached versions
5. ALWAYS specify exactly what to extract — never "get the page" or "summarize"
### 2. INSTALL an existing skill
```bash
# From known repos
npx -y openskills install <owner/repo/skill-name> -g
# Or manually
# 1. Fetch the SKILL.md content
# 2. Write to ~/.claude/skills/<skill-name>/SKILL.md
# 3. Copy any scripts/, references/, assets/ if present
```
After install, verify:
- SKILL.md has valid frontmatter (name, description)
- Description doesn't overlap with existing skills
- Fits the layered architecture: universal → lang → domain → target
### 3. CREATE a new skill from scratch
Follow Anthropic's skill-creator principles:
A) **Size = f(content)** — can be 10 lines or 500, depends on how much Claude DOESN'T know
B) **CRITICAL: Don't teach what Claude already knows!**
C) **When in doubt — EXCLUDE** (easier to add later than to remove)
D) **Minimal code examples** — only to illustrate a gotcha, not full solutions
E) **Always add `description` to frontmatter** — max 5-6 words, as short as possible. Without it Claude won't load the skill.
F) **Do NOT add `disable-model-invocation`** — skills must be callable via Skill() tool. Discovery chain: workflow `think` state → domain mapping → `Skill(name)`.
G) Use progressive disclosure:
- SKILL.md body (<5k words) = loaded when triggered via Skill()
- references/ = loaded on demand
**Splitting an oversized skill into references/:**
- Extract ONLY clusters that are NOT needed in every session (macro authoring, target-specific runtime edges, tool-self-development recipes). Everyday gotchas stay in the body — the model can't know it needs a gotcha it hasn't seen.
- Split by error loudness: content whose absence fails LOUDLY (compiler error, CLI failure → model goes looking) is safe to extract; content preventing SILENT bugs keeps at least a one-line trigger in the body.
- Each extracted section leaves a one-line index entry in the body: trap + fix in one line (recognition stays guaranteed, details load on demand).
- Index header gets an IMPERATIVE trigger ("BEFORE writing macro code → Read references/macros.md"), never a passive "see also".
- Move content VERBATIM (mechanical line-range split); verify every original heading appears exactly once across body + references.
- If the skill has a repo/template source of truth, write BOTH copies and diff them.
### ⚠️ What to include vs exclude in skills
**NEVER include** (Claude already knows this):
- Basic syntax of mainstream languages
- Standard library functions that are well-documented
- Common design patterns (singleton, factory, observer)
- General programming principles (DRY, SOLID)
- Popular framework basics (React, ASP.NET, Django)
- **Well-known patterns with full examples** (multi-stage Docker builds, async/await)
- **Obvious best practices** (use .gitignore, validate input)
- **Standard CLI commands** (docker run, git commit, npm install)
**ALWAYS include** (Claude needs this):
- **Gotchas and pitfalls** — things Claude commonly gets wrong
- **Subtle differences** — from similar languages/frameworks
- **Non-obvious conventions** — that differ from common patterns
- **Version-specific changes** — recent updates Claude may not know
- **Integration quirks** — how things work together in practice
- **User's preferences** — always in preferences-* skills
- **Niche topics** — obscure APIs, legacy systems, specialized domains
**Process for creating a lang-* or domain-* skill:**
1. Start with EMPTY file
2. Research web for "gotchas", "common mistakes", "pitfalls" in this domain
3. For each finding — two-model filter (Opus + Sonnet):
- Both models know it → SKIP (water)
- At least one doesn't know → INCLUDE
4. Specific numbers/boundaries → always verify by computation, record exact values
5. If nothing passes the filter → maybe this skill isn't needed
**Two-model consensus** (mirrors water-removal):
- Remove what BOTH models know
- Add what at LEAST ONE model doesn't know
**Gotcha vs Pattern — examples:**
```
✗ EXCLUDE: "Use multi-stage builds to reduce image size"
(well-known pattern, Claude knows this)
✓ INCLUDE: "COPY --from=0 uses stage INDEX, not name — breaks if stages reordered"
(gotcha, easy to miss)
✗ EXCLUDE: "Use async/await for asynchronous code"
(basic syntax)
✓ INCLUDE: "ConfigureAwait(false) in library code — otherwise deadlock in UI"
(subtle gotcha, context-dependent)
```
Structure:
```
~/.claude/skills/<skill-name>/
├── SKILL.md # Required: frontmatter + instructions
├── references/ # Optional: detailed docs, schemas
├── scripts/ # Optional: executable helpers
└── assets/ # Optional: templates, samples
```
Naming for layered architecture:
- Universal: `code-writing`, `architecture`, `testing`, `refactoring`
- Language: `lang-csharp`, `lang-haxe`, `lang-python`
- Domain: `domain-unity`, `domain-dotnet`, `domain-gamedev`
- Target: `target-hashlink`, `target-aspnet`, `target-webgl`
### 4. CONVERT documentation into a skill
For turning language/framework docs into a skill:
A) Fetch documentation using web-reading chain
B) Extract:
- Core idioms and conventions
- Common patterns and anti-patterns
- API quick reference (signatures, not full docs)
- Gotchas and common mistakes
C) Structure as SKILL.md — focus on what Claude wouldn't know
D) Move detailed API references to references/ directory
E) Write precise description for auto-invocation
### 5. ENRICH skill from observed error
Triggered by reflection when Claude makes a verifiable mistake.
1. Identify the error and the skill it belongs to
2. Research the correct answer: code verification → web docs → web search
3. Verify the correct answer by running code (if possible)
4. Add ONLY the verified correction to the existing skill
5. Format: show the wrong thing and the right thing with exact values
6. ABSTRACT the incident before writing: a universal/lang skill must carry
NO project nouns or domain story details — rule + tell stay precise,
the example compresses to 1-3 abstract lines ("a moving object", "a
large file" — not the game entity or the repo it happened in).
A lesson whose substance IS domain-specific goes to a domain-* skill,
not the universal one. Project specifics leaking through incident
stories was a real recurring defect — this step is the gate.
Example flow: Claude writes `Fib(46) overflows Int32` → verification shows Fib(46) fits,
Fib(47) overflows → add the verified table, with exact numbers, to the skill that owns the domain.
### 6. UPDATE an existing skill (manual)
```bash
# Via openskills (if installed from repo)
npx -y openskills update <skill-name>
# Or manually
# 1. Read current ~/.claude/skills/<skill-name>/SKILL.md
# 2. Identify what's missing or wrong
# 3. Edit with improvements
# 4. Verify description still fits
```
### 7. LIST and AUDIT current skills
```bash
ls ~/.claude/skills/
```
Check for:
- Overlapping descriptions between skills
- Skills that are too large (>500 lines)
- Missing skills for languages/domains being used
- Outdated information
### 8. OPTIMIZE skills (on model version change)
When Claude version changes (e.g., 4.5 → 5.0), run optimization:
**Trigger:** User says "optimize skills" or new model version detected.
**Process for each skill:**
1. Read the skill content
2. For each piece of information, ask:
- "Does the NEW model already know this?" → REMOVE if yes
- "Is this a gotcha/pitfall that's still relevant?" → KEEP
- "Is this user's preference?" → NEVER TOUCH (preferences-*)
- "Has this API/convention changed?" → UPDATE from fresh research
3. Re-test: does the skill still add value?
4. If skill becomes nearly empty → consider deleting it
**What to keep regardless of model version:**
- User preferences (preferences-*)
- Behavioral/meta skills (reflection)
- Infrastructure skills (web-reading, mcp-setup)
- Recent version-specific changes (last 6-12 months)
- Niche domains (ANE, Re-ID pipelines)
**What to aggressively prune:**
- Basic syntax of mainstream languages
- Well-documented standard library functions
- General programming principles
- Popular framework basics
**Deduplicate with preferences:**
During optimization, check preferences-* skills for this language/domain.
If a rule exists in preferences-*, REMOVE it from the base skill.
User preferences always win — no need to duplicate.
Example: if preferences-haxe says "use final class", remove any mention
of final class conventions from lang-haxe.
**Log optimizations:**
After optimization, note in MEMORY.md:
- Date optimized
- Model version optimized for
- What was removed/kept/updated
### 9. UPDATE selector domain mappings after creating new skills
**MANDATORY:** After creating or installing any new skill, update the domain mapping
in `~/.claude/skills/coding-skill-selector/SKILL.md` — one place.
Add the new skill to the appropriate section (by extension or by domain), e.g.:
```
- NewDomain → `Skill("domain-newdomain")`
```
**This single skill is loaded at the skill-gate states of all code-related workflows (coding, debugging, bug-fix, code-review, etc.).**
### Language rule
All skills MUST be written in English only. Never mix languages in skill files.
### Validation checklist
Before finishing any skill operation:
- [ ] Frontmatter has `name` + short `description` (no disable-model-invocation)
- [ ] Name is hyphen-case, max 64 chars
- [ ] SKILL.md ≤500 lines (size driven by content, not arbitrary target)
- [ ] Follows layered architecture (universal/lang/domain/target)
- [ ] Only gotchas/pitfalls — no basic patterns Claude already knows
- [ ] No provenance notes (dates, "verified on X", one-off measurements) — skill content is timeless method, not a change journal
- [ ] No machine-specific facts (local paths, symlink layouts, this-machine install quirks) in skills that ship with a plugin/template — content must hold for ANY user; machine-specifics belong in memory
- [ ] If skill is nearly empty → maybe it's not needed
- [ ] **selector domain mapping updated** (coding-skill-selector skill)
- [ ] **Bundled twin updated**: if the skill also ships inside a plugin repo
(e.g. `mcp-workflow-engine/templates/skills/<name>/`), COPY the edited
file over the twin (`cp`, never re-type — hand-applied "same" edits
drift by whitespace) and verify with the repo's
`scripts/check-skill-sync.sh`. An intentionally-different twin
(generic template vs personal copy) belongs in `.skillsyncignore`
- [ ] **Shipped version recorded**: after any edit under `templates/skills/` of a plugin repo that ships a copy-provisioning hook, run its history script (`npm run skills:history` in `mcp-workflow-engine`) — a user's unedited older copy is recognised, and updated, only by the versions that table lists