> "A well-designed skill is a contract: it promises a procedure, guarantees quality criteria, and warns about anti-patterns."
From jm-adknpx claudepluginhub javimontano/jm-adk-alfaThis skill is limited to using the following tools:
agents/guardian.mdagents/lead.mdagents/specialist.mdagents/support.mdevals/evals.jsonknowledge/body-of-knowledge.mdknowledge/knowledge-graph.mdprompts/meta.mdprompts/primary.mdprompts/variations/deep.mdprompts/variations/quick.mdreferences/skill-body-patterns.mdreferences/skill-frontmatter-spec.mdtemplates/output.docx.mdtemplates/output.html"A well-designed skill is a contract: it promises a procedure, guarantees quality criteria, and warns about anti-patterns."
Design a single plugin skill in full detail. Produces a complete SKILL.md specification with frontmatter, guiding principle, numbered procedure, quality criteria, anti-patterns, and edge cases. Validates against MOAT quality dimensions. [EXPLICIT]
[DOC] for plan-derived info, [STAKEHOLDER] for user input.Draft the complete YAML frontmatter using ALL official fields. The full field catalog:
| Field | Required | Type | Description |
|---|---|---|---|
name | YES | string | kebab-case skill identifier |
description | YES | string | Purpose + trigger phrases. Multi-line with > for long descriptions |
argument-hint | no | string | Placeholder showing expected arguments. Supports $ARGUMENTS, $1, $2, ${CLAUDE_SKILL_DIR} |
disable-model-invocation | no | boolean | If true, skill cannot be auto-invoked by the model (default: false) |
user-invocable | no | boolean | If true, user can invoke directly. If false, only agents/other skills can invoke |
allowed-tools | no | list[string] | Whitelist of tools the skill may use. Enforces least privilege |
model | no | string | Override model for this skill (e.g., claude-sonnet-4-20250514) |
context | no | list[object] | Additional context files to load. Objects with type and path fields |
agent | no | string | Override which agent handles this skill |
hooks | no | object | Skill-level hook definitions (applies only during skill execution) |
String substitutions available in argument-hint and description:
$ARGUMENTS -- Full argument string passed by the user.$1, $2, ..., $N -- Positional arguments.${CLAUDE_SKILL_DIR} -- Absolute path to the skill's directory at runtime.Apply least privilege: include only tools the skill genuinely needs. Read-only skills must NOT include Write. [EXPLICIT]
[CODIGO]"Read, Glob, Grep (never Write). [EXPLICIT]Read, Glob, Grep, Bash. [EXPLICIT]Read, Write, Glob, Grep. [EXPLICIT]Read, Write, Glob, Grep, Bash. [EXPLICIT][CONFIG]> "Quote text here."references/skill-frontmatter-spec.md and references/skill-body-patterns.md.Lines: {count}
Tools: {list}
MOAT Depth: {depth}
Quality Score: {score}/100
[CONFIG][DOC][DOC][DOC][DOC][CONFIG]audit-content-quality.[DOC], [CONFIG], [CODIGO]) are mandatory per PQA conventions but are not part of the official Claude Code plugin spec.Bad skill design:
---
name: my-skill
description: Does stuff
allowed-tools:
- Read
- Write
- Bash
---
# My Skill
1. Do the thing.
2. Return result.
Missing: no trigger phrases in description, Write included for a read-only skill, vague steps, no quality criteria, no anti-patterns, no edge cases. [EXPLICIT]
Good skill design:
---
name: validate-config
description: >
Validates configuration files for correctness and consistency. [EXPLICIT]
Trigger: validate config, check config, config audit. [EXPLICIT]
allowed-tools:
- Read
- Glob
- Grep
---
# Validate Config
> "Configuration is code that doesn't get tested -- until it breaks production."
## Procedure
### Step 1 -- Locate Config Files
- Glob for `*.json`, `*.yaml`, `*.toml` in plugin root. [DOC]
...
## Quality Criteria
- [ ] Every config file is validated; none silently skipped.
...
## Anti-Patterns
1. Accepting malformed YAML because the parser auto-corrects... [EXPLICIT]
## Edge Cases
1. Plugin with zero config files -- report INFO, do not error. [EXPLICIT]
Includes: trigger phrases, least-privilege tools, guiding quote, structured steps with evidence tags, quality criteria, anti-patterns, edge cases. [EXPLICIT]
Write in allowed-tools for a read-only analysis skill. [EXPLICIT]disable-model-invocation: true without justification (limits discoverability). [EXPLICIT]argument-hint should be omitted, not set to empty string. [EXPLICIT]user-invocable: false and omit from command routing. [EXPLICIT]model field with justification. [EXPLICIT]Example invocations:
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.