Ai Skill Manager

AI Skill Manager

When to Use

• Inventory skills in a repo or org catalog; find gaps and duplicates
• Audit description frontmatter for clear triggers and routing
• Add or fix When NOT to Use and Related skills cross-links
• Run batch validation or package .skill bundles for distribution
• Split an overloaded skill or merge overlapping ones
• Deprecate or rename a skill without breaking consumers
• Define governance: review checklist, owners, publish cadence
• Triage security concerns in skill content (secrets, dangerous scripts)

When NOT to Use

• Step-by-step creation of one new skill → use skill-creator (init_skill.py, package_skill.py)
• Design RAG, agents, eval harnesses → ai-engineer
• Model/prompt release ops and cost rituals → ai-lead-ops
• AI regulatory policy registers → ai-risk-governance
• Rewrite prompts inside a domain skill → prompt-engineer

Related skills

Core Workflows

1. Portfolio inventory

For each skill directory with SKILL.md, record:

Flag: same trigger keywords in multiple description fields.

See `references/catalog_inventory.md`.

2. Quality gate (per skill)

Before merge or publish:

1. name matches folder name (hyphen-case, ≤64 chars) 2. description includes what + when to use + when NOT (peer skill names) 3. Body ≤ ~500 lines; deep detail in references/ 4. No README/CHANGELOG inside skill folder 5. Run validator (below)

See `references/quality_standards.md`.

3. Routing and overlap

When two skills trigger on the same user phrase:

1. Pick primary owner of the workflow 2. Move triggers into primary description; add explicit negation in the other 3. Add reciprocal Related skills rows 4. If overlap >30% of workflows, plan split or merge

See `references/routing_and_overlap.md`.

4. Lifecycle

See `references/skill_lifecycle.md`.

5. Validate and package

Single skill:

python3 ~/.claude/skills/skill-creator/scripts/quick_validate.py <path/to/skill-dir>
python3 ~/.claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-dir> ./dist

Entire repo (this skill bundle):

bash ai-skill-manager/scripts/validate_all_skills.sh /path/to/Agentic-Enteprises-Skill

See `references/validation_packaging.md`.

6. Security and supply chain

Review before org-wide install:

• No secrets, API keys, or customer data in skills
• Scripts: least privilege; no curl | bash patterns
• description must not instruct bypassing safety or compliance
• Third-party skills: same checklist + license note

See `references/portfolio_governance.md`.

Output standards

• Inventory as table: name, purpose, triggers, overlap risk, last reviewed
• Change proposals: what moves, which skills get updated cross-links
• Deprecation notice: replacement skill name and migration sentence for description

When to load references

• Inventory and catalog → references/catalog_inventory.md
• Review checklist → references/quality_standards.md
• Dedup and routing → references/routing_and_overlap.md
• Split/merge/deprecate → references/skill_lifecycle.md
• validate/package commands → references/validation_packaging.md
• RACI and publish policy → references/portfolio_governance.md

Catalog and inventory

Table of contents

1. Scan the repo 2. Inventory table 3. Gap and duplicate signals

Scan the repo

Skills in this layout: one directory per skill, SKILL.md at depth 2:

repo/
├── skill-a/SKILL.md
├── skill-b/SKILL.md
└── ...

List names:

find . -mindepth 2 -maxdepth 2 -name SKILL.md | sed 's|/SKILL.md||' | xargs -I{} basename {}

Inventory table

Refresh quarterly or when adding/removing skills.

Gap and duplicate signals

Gap: user requests that match no description keyword — candidate new skill or extend existing.

Duplicate: same verbs in two descriptions (e.g. "incident" in both devops and incident-management-engineer) — tighten when NOT lines.

Orphan: skill with no inbound cross-links from peers — add Related skills rows in adjacent domains.

Repo-level index for humans may live in root README.md; do not add per-skill README files.

Portfolio governance

Table of contents

1. Roles 2. Publish workflow 3. Security review 4. Versioning

Roles

Publish workflow

1. Author opens PR with skill or delta 2. Owner + skill manager review checklist (quality_standards.md) 3. validate_all_skills.sh green 4. Cross-links updated in peer skills 5. Merge; tag release if distributing .skill bundles 6. Announce via communication-lead if org-wide behavior changes

Security review

Block publish if skill contains:

• Credentials, tokens, private URLs, customer examples
• Scripts that disable safeguards or exfiltrate data
• Instructions to ignore legal, export, or compliance rules
• Unsigned third-party scripts without review

Prefer references to public docs over copying restricted internal policy text.

Versioning

• Git tags on repo for catalog snapshots (e.g. skills-2026.05)
• Per-skill breaking change: note in PR; update deprecated skill description
• Agent installs: pin tag or hash; document upgrade path for teams

Align with Agent Skills open format when integrating external tooling.

Quality standards

Table of contents

1. Frontmatter 2. SKILL.md body 3. Bundled resources 4. Review checklist

Frontmatter

Required YAML keys only: name, description (optional: license, allowed-tools, metadata per validator).

• name: hyphen-case, matches directory name, ≤64 characters
• description: multi-line | block; includes:
• Capability summary
• Use when — concrete triggers
• Not for — peer skill names (routing)

Do not put "When to use" only in the body — agents read description before loading the body.

SKILL.md body

• Imperative voice
• When to Use / When NOT to Use / Related skills table
• Core workflows numbered; link to references/ for depth
• Target <500 lines in body

Bundled resources

Forbidden inside skill folder: README.md, CHANGELOG.md, install guides.

Review checklist

• [ ] Validator passes
• [ ] No secrets or env-specific URLs
• [ ] Scripts run in clean shell (if present)
• [ ] Cross-links added to ≥2 related skills
• [ ] No duplicate of skill-creator content (point to skill-creator instead)

Routing and overlap

Table of contents

1. Routing layers 2. Disambiguation pattern 3. Merge vs split heuristic

Routing layers

Optimize layer 1 first — it is always in context.

Disambiguation pattern

Primary skill description:

Use when [specific triggers]—not for [peer-a], [peer-b].

Secondary skill description:

Use when [narrow triggers]—not for [primary] ([when primary wins]).

Add matching rows in both Related skills tables.

Merge vs split heuristic

Common pairs in this repo: business-consultant vs business-analyst; incident-management-engineer vs support-engineer; ai-engineer vs applied-ai-architect-commercial-enterprise.

Skill lifecycle

Table of contents

1. Create 2. Iterate 3. Split 4. Merge 5. Deprecate

Create

Use skill-creator process:

python3 ~/.claude/skills/skill-creator/scripts/init_skill.py <skill-name> --path <repo-root>

Then: references → SKILL.md → validate → cross-link peers → optional package.

Only create a new skill when an existing one cannot absorb workflows without bloating triggers.

Iterate

After real usage:

1. Move verbose content from SKILL.md → references/ 2. Tighten description if misfires reported 3. Re-run validator and batch script

Split

When:

• Multiple frameworks (e.g. AWS vs Azure) each >100 lines
• Distinct audiences with different triggers

Steps:

1. Create new skill with focused description 2. Move reference files to new folder 3. Shorten original; add When NOT → new skill 4. Update cross-links across repo (grep skill name)

Merge

When:

• Duplicate triggers cause wrong skill >20% of time
• Maintenance burden exceeds value

Steps:

1. Pick surviving name 2. Fold references; dedupe headings 3. Union description triggers (carefully) 4. Deprecate removed skill (below)

Deprecate

1. Add to old skill description: Deprecated—use <new-name> for ... 2. Remove old skill from install bundles after one release 3. Grep repo for backtick references; update tables 4. Keep directory one cycle for git history, then delete if policy allows

Validation and packaging

Table of contents

1. Single skill 2. Batch validate 3. Package for distribution 4. CI suggestion

Single skill

python3 ~/.claude/skills/skill-creator/scripts/quick_validate.py path/to/skill-dir

Fix reported YAML, naming, or description issues before merge.

Batch validate

From repo root:

bash ai-skill-manager/scripts/validate_all_skills.sh .

Or set SKILL_VALIDATOR if skill-creator lives elsewhere.

Exit non-zero if any skill fails — use in CI.

Package for distribution

mkdir -p dist
python3 ~/.claude/skills/skill-creator/scripts/package_skill.py path/to/skill-dir ./dist

Produces dist/<skill-name>.skill (zip). Package only after validation passes.

CI suggestion

On pull requests that touch */SKILL.md:

1. Run validate_all_skills.sh 2. Optional: diff grep for removed skill names → require cross-link updates

Do not package all skills on every PR unless releasing a bundle.