Help us improve
Share bugs, ideas, or general feedback.
From hb
Scaffolds new Claude Code skills with proper structure, progressive disclosure, and bundled resource conventions.
npx claudepluginhub helderberto/agent-skills --plugin hbHow this skill is triggered — by the user, by Claude, or both
Slash command
/hb:create-skillThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
1. **Gather requirements** — ask the user (use AskUserQuestion when available; otherwise present numbered options):
Guides creation of new Claude Code skills with SKILL.md templates, structure, progressive disclosure, review checklists, and optional scripts/references.
Guides creation of new agent skills with templates, progressive disclosure, and bundled utility scripts. Use for building new skills.
Creates, updates, or validates SKILL.md agent skills including frontmatter authoring, bundled resource planning, and three-phase discoverability validation.
Share bugs, ideas, or general feedback.
ls skills/ and read 1–2 neighbors to match conventions.SKILL.md; split deep material into references/ if it exceeds ~150 lines; add scripts/ only for deterministic helpers.skill-name/
├── SKILL.md # Required. Metadata + instructions.
├── references/ # Optional. Long-form docs the agent reads on demand.
│ └── <topic>.md
├── scripts/ # Optional. Deterministic helpers (.sh, .py) called via Bash.
│ └── helper.sh
└── assets/ # Optional. Files used in output (templates, icons, fonts).
└── template.md
Keep the entry point in SKILL.md. Link from SKILL.md to references/<topic>.md rather than inlining — preserves progressive disclosure.
name + description) — always in context (~100 words). Sole signal for triggering.SKILL.md body — loaded when skill triggers. Keep under ~150 lines; the spec ceiling is ~500.references/, scripts/, assets/) — loaded on demand or executed without loading.---
name: skill-name
description: One sentence what it does. Use when [triggers]. Don't use when [anti-triggers].
---
# Skill Name
## Workflow
[numbered steps]
## Rules
[hard constraints]
## Error Handling
[if X — do Y]
Orchestrator skills (e.g. review, ship) replace Workflow with explicit phases that announce each sub-skill being invoked.
| Field | Required | Notes |
|---|---|---|
name | yes | kebab-case, matches directory. Avoid version suffixes (-v2, -new) — evolve in place or deprecate |
description | yes | Agent's only signal for when to load this skill |
argument-hint | no | One-line hint shown next to the skill name (e.g. '[slug]', '<idea>') |
Avoid compatibility: and allowed-tools: — legacy npx skills CLI fields, not part of the Claude Code plugin spec.
The description is the only thing the agent sees when deciding which skill to load. It's surfaced in the system prompt alongside every other installed skill — the agent reads descriptions and picks one based on the user's request.
Goal: give the agent just enough to know
Format:
Use when [triggers]Don't use for [anti-triggers]Combat under-triggering: Claude tends to under-trigger skills. If a skill is useful but rarely fires, make the description more assertive — list extra phrases the user might say, name file types or contexts explicitly, even add Make sure to use this skill whenever... when warranted. Anti-triggers stay important, but the trigger clause should be generous.
Good:
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction. Don't use for image OCR (use vision skill) or DOCX files.
Bad:
Helps with documents.
The bad example gives the agent no way to distinguish this from any other document skill.
Add scripts/ helpers when:
Scripts save tokens and improve reliability vs. ad-hoc generated code.
Split into references/<topic>.md when:
SKILL.md exceeds ~150 linesDomain organization: when a skill supports multiple variants, split by variant so the agent loads only the relevant one:
cloud-deploy/
├── SKILL.md # workflow + variant selection
└── references/
├── aws.md
├── gcp.md
└── azure.md
Run X, Check Y — not You should run X)ALWAYS/NEVER in caps. Today's models have theory of mind; reasoning lands better than rigid rulesMUST is fine when a hard constraint exists; a wall of caps is a yellow flag — reframe and explainWorkflow skills can pre-load shell output via the ! prefix:
## Pre-loaded context
- Status: !`git status`
- Diff: !`git diff HEAD`
The harness executes each command and injects its output as context. Use for state the skill always needs — git status, package.json, file listings.
Before shipping a new or modified skill:
name: fieldSKILL.md under ~150 lines (split into references/ if longer)compatibility: or allowed-tools: legacy fields[validate-code](../validate-code/SKILL.md))AGENTS.md intent → skill mapping"Helps with testing." — uselessreferences/