skill-manager

name	skill-manager
source	botcore
description	Create, maintain, and validate agent skills following the Agent Skills open standard (agentskills.io). Covers SKILL.md format, frontmatter fields (open standard + Claude Code extensions), progressive disclosure, hooks, resource scripts, naming conventions, routing tables, and automated quality checks. Use when creating new skills, auditing existing skills, fixing lint errors, adding hooks to skills, or writing resource scripts for deterministic offloading. Triggers: create skill, new skill, skill lint, audit skills, SKILL.md, hooks, resource scripts, progressive disclosure, Agent Skills, open standard, skill architecture, deterministic offloading.
version	3.0.0
triggers	["create skill","new skill","skill lint","audit skills","skill template","skill-manager","SKILL.md","skill best practices","hooks","resource scripts","progressive disclosure","Agent Skills","open standard","deterministic offloading","subagents"]
portable	true

Skill Manager

Expert guidance for creating, maintaining, and validating agent skills across projects and platforms (Claude Code, VS Code Copilot, Copilot CLI, Cursor, and other Agent Skills-compatible tools).

Capabilities

1. Create Skills — Generate new skills with proper structure and metadata
2. Lint Skills — Automated validation against quality rules
3. Maintain Skills — Update, refactor, and organize existing skills
4. Distributed Architecture — Manage skills across multiple repositories and scopes
5. Hook Integration — Add guardrail and janitor hooks to skills
6. Resource Scripts — Deterministic offloading for parsing, linting, and API calls

Quick Commands

Each repo provides a skill linter via its own CLI or MCP server. Check your repo's AGENTS.md for the exact command.

# Typical patterns (replace <cli> with your repo's command)
<cli> skill-lint .claude/skills              # Lint all skills
<cli> skill-lint .claude/skills/my-skill     # Lint single skill
<cli> skill-lint .claude/skills --strict     # Warnings = errors

Routing Logic

Request type	Load reference
SKILL.md format, frontmatter syntax	references/format.md
Routing tables, progressive loading	references/routing.md
Description writing, trigger keywords	references/descriptions.md
Reference file organization	references/reference-files.md
Skill architecture, folder structure	references/architecture.md
Multi-repo skill distribution, scopes	references/distributed-skills.md
Linter rules and fixes	references/linter-rules.md
Full technical specification	references/skills-specification.md
Hook integration (guardrails, janitors)	references/hooks.md
Resource scripts, deterministic offloading	references/resource-scripts.md

Core Principles

1. Progressive Disclosure (Three Stages)

Skills load content in stages to optimize context token usage:

Stage	What loads	When	Budget
Discovery	Frontmatter only (name, description)	Session start — all skills	~30 tokens per skill
Brain	SKILL.md body	When skill is triggered	< 500 lines
Resources	References, scripts, assets	When explicitly needed	No limit

Design for minimal initial context, with deep references on-demand. The total description budget across all skills is ~2% of the context window (~16K chars fallback).

2. Distributed Architecture

Product-specific skills live with their product; general skills live in a shared location.

Skills resolve by scope priority: Enterprise > Personal (~/.claude/skills/) > Project (.claude/skills/) > Plugin.

~/.claude/skills/                 # Personal (all projects)
├── problem-solver/
└── researcher/

project-a/.claude/skills/         # Project-specific
└── domain-logic/

project-b/.claude/skills/         # Project-specific
└── data-pipeline/

3. Naming Convention

Format rules:

Pattern	Example	Rule
Lowercase + hyphens	problem-solver	Required (open standard)
Match parent directory	commit/SKILL.md → name: commit	Required
No consecutive hyphens	my-skill (not my--skill)	Required
Max 64 characters	—	Required
Noun-first	code-reviewer (not review-code)	Required

Naming tiers — the suffix signals what kind of help the skill provides:

Suffix	Meaning	Examples
(bare noun)	Action — does the thing	commit, pr, release, hotfix, review
-role (-er/-or)	Agent — works with you actively	code-reviewer, mcp-builder, test-writer, security-auditor
-learn	Reference — teaches patterns and guidance	caching-learn, authentication-learn, concurrency-learn

How to choose: Pick the noun (domain) first, then the suffix:

• Will it perform an action when invoked? → bare noun (commit, release)
• Will it actively collaborate on a task? → noun-role (code-reviewer, problem-solver)
• Will it teach patterns and provide reference? → noun-learn (caching-learn, state-learn)

4. Deterministic Offloading

Never rely on the LLM for deterministic work. Use resource scripts for regex, parsing, math, API pagination, and data transformation.

Scripts output clean Markdown/JSON to stdout. Recovery instructions go to stderr for the AI.

5. Quality Gates

Run the skill linter before committing any skill changes (see AGENTS.md for your repo's command).

Create a New Skill

Step 1: Choose Location

• General skill (applies to multiple projects) → Shared skills directory
• Product-specific (only for one project) → {project}/.claude/skills/

Step 2: Create Structure

{skills-dir}/{skill-name}/
├── SKILL.md              # Required: Main entry point
├── references/           # Optional: Deep-dive documents
│   └── {topic}.md
├── scripts/              # Optional: Deterministic helpers
│   └── {helper}.py
└── hooks/                # Optional: Guardrail/janitor hooks
    └── {hook}.sh

Step 3: Use Template

Copy from templates/skill.template.md and fill in:

• name: — Must match the parent directory name
• description: — What it does and when to use it (max 1024 chars)
• version: — Start at "1.0.0"
• triggers: — Keywords for routing (array format)

Step 4: Validate

Run the skill linter (see AGENTS.md for your repo's command) and fix any errors before committing.

Frontmatter Reference

Open Standard Fields (agentskills.io)

name: skill-manager
description: >               # Required. Max 1024 chars. Routing trigger.
  What this skill does.
  Use when building X.
license: MIT                 # Optional. SPDX identifier
compatibility: >             # Optional. Max 500 chars. Version/platform notes
  Claude Code 2.x, VS Code Copilot, Cursor
metadata:                    # Optional. Key-value pairs
  author: team-name
allowed-tools:               # Optional (experimental). Restrict tool access
  - Read
  - Grep

Claude Code Extension Fields

version: "1.0.0"            # Track skill evolution
triggers:                    # Keywords for routing (array format)
  - keyword1
  - keyword2
portable: true               # Skill used across projects
context: fork                # Isolate in subagent
user-invocable: true         # Show in slash-command menu (default: true)
disable-model-invocation: true  # User-only, removed from model context
agent: general-purpose       # Agent type (Explore, Plan, general-purpose, custom)
model: claude-sonnet         # Override model for this skill
argument-hint: "file path"   # Hint for argument placeholder
hooks:                       # Inline hook definitions
  - event: PreToolUse
    matcher: Write
    command: "${CLAUDE_PLUGIN_ROOT}/hooks/check.sh"

Linter Rules Summary

ID	Severity	Rule
SK001	Error	Frontmatter required
SK002	Error	name: field required
SK003	Error	description: field required
SK004	Warning	Name must be lowercase-hyphenated, match dir, no consecutive hyphens
SK005	Warning	Description < 1024 chars
SK006	Warning	Include triggers (frontmatter or inline)
SK008	Error	Linked references must exist
SK010	Error	No placeholder text
SK011	Info	Use {baseDir} for portable skills
SK012	Warning	Use SKILL.md (uppercase)
SK014	Warning	No orphan reference files
SK015	Error	No duplicate names
SK017	Info	Migrate inline triggers to frontmatter

Full list: references/linter-rules.md

When to Escalate

• Cross-team skill conflicts — Skills with overlapping domains need governance review
• Breaking changes — Renaming or restructuring skills used by other projects
• New patterns — Novel skill capabilities not covered by existing guidance
• Hook security — Hooks that block tool execution need careful review