Guides design and optimization of Claude Code skills and MCP tools with best practices for metadata, descriptions, triggers, progressive disclosure, and testing.
npx claudepluginhub joshuarweaver/cascade-code-general-misc-1 --plugin pproenca-dot-skills-1This skill uses the workspace's default tool permissions.
Design and development guide for AI agent skills, including Claude Code skills and MCP tools. Contains 46 rules across 8 categories, prioritized by impact to guide skill creation, review, and optimization.
Applies Acme Corporation brand guidelines including colors, fonts, layouts, and messaging to generated PowerPoint, Excel, and PDF documents.
Builds DCF models with sensitivity analysis, Monte Carlo simulations, and scenario planning for investment valuation and risk assessment.
Calculates profitability (ROE, margins), liquidity (current ratio), leverage, efficiency, and valuation (P/E, EV/EBITDA) ratios from financial statements in CSV, JSON, text, or Excel for investment analysis.
Design and development guide for AI agent skills, including Claude Code skills and MCP tools. Contains 46 rules across 8 categories, prioritized by impact to guide skill creation, review, and optimization.
1. Descriptions drive activation. Claude selects skills based on description matching against user intent. Include specific capabilities, trigger keywords, and negative cases. A skill with a vague description activates inconsistently or never.
2. Front-load critical instructions. Claude may truncate long content. Place non-negotiable rules in the first 100 lines. Bury important constraints at the end and they get ignored.
3. Progressive disclosure saves tokens. Load detailed content only when needed. A 2000-line skill wastes context on every activation. Structure as: SKILL.md (overview) → references/ (details) → scripts/ (execution).
4. Test activation, not just execution. A skill that works perfectly but never triggers provides zero value. Test with real user phrases, synonyms, and edge cases before deployment.
5. One skill per domain. Overlapping skills create activation conflicts. Split by clear boundaries (language, framework, workflow stage) with distinct trigger keywords.
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Skill Metadata Design | CRITICAL | meta- |
| 2 | Description Engineering | CRITICAL | desc- |
| 3 | Content Structure | HIGH | struct- |
| 4 | Trigger Optimization | HIGH | trigger- |
| 5 | Progressive Disclosure | MEDIUM-HIGH | prog- |
| 6 | MCP Tool Design | MEDIUM | mcp- |
| 7 | Testing and Validation | MEDIUM | test- |
| 8 | Maintenance and Distribution | LOW-MEDIUM | maint- |
meta-name-format - Use lowercase hyphenated skill namesmeta-name-hyphen-boundaries - Never start or end names with hyphensmeta-name-no-consecutive-hyphens - Avoid consecutive hyphens in namesmeta-name-uniqueness - Ensure skill names are globally uniquemeta-required-frontmatter - Include all required frontmatter fieldsmeta-allowed-frontmatter-fields - Use only allowed frontmatter fieldsmeta-frontmatter-yaml-syntax - Use valid YAML frontmatter syntaxmeta-name-length - Keep skill names under 64 charactersmeta-directory-match - Match skill name to directory namedesc-specific-capabilities - Name specific capabilities in descriptiondesc-trigger-keywords - Include user trigger keywords in descriptiondesc-third-person-voice - Write descriptions in third persondesc-length-optimization - Optimize description length for discoverydesc-avoid-vague-terms - Avoid vague terms in descriptionsdesc-differentiate-similar-skills - Differentiate similar skills with distinct triggersdesc-include-negative-cases - Include negative cases for precisionstruct-header-hierarchy - Use consistent header hierarchystruct-instructions-first - Put critical instructions early in contentstruct-imperative-instructions - Write instructions in imperative moodstruct-code-blocks-with-language - Specify language in code blocksstruct-line-limit - Keep SKILL.md under 500 linesstruct-single-responsibility - One skill per domaintrigger-slash-command-aliases - Include slash command aliases in descriptiontrigger-file-type-patterns - Include file type patterns in descriptiontrigger-workflow-stages - Reference workflow stages in descriptiontrigger-error-patterns - Include error patterns in debugging skillstrigger-synonym-coverage - Cover synonyms and alternate phrasingsprog-three-level-disclosure - Implement three-level progressive disclosureprog-one-level-deep-links - Limit reference links to one level deepprog-scripts-execute-not-read - Execute scripts instead of reading codeprog-lazy-load-examples - Lazy load examples and reference materialprog-mutual-exclusion - Separate mutually exclusive contextsmcp-tool-naming - Use clear action-object tool namesmcp-parameter-descriptions - Document all tool parametersmcp-error-messages - Return actionable error messagesmcp-tool-scope - Design single-purpose toolsmcp-allowed-tools - Use allowed-tools for safety constraintsmcp-idempotent-operations - Design idempotent tool operationstest-trigger-phrases - Test skill activation with real user phrasestest-edge-cases - Test skills with edge case inputstest-negative-scenarios - Test that skills do NOT trigger on unrelated requeststest-instruction-clarity - Test instructions with fresh contextmaint-semantic-versioning - Use semantic versioning for skill releasesmaint-changelog - Maintain a changelog for skill updatesmaint-plugin-packaging - Package skills as plugins for distributionmaint-audit-security - Audit skills before installing from external sourcesCopy assets/templates/_template.md and follow the frontmatter schema:
---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact (e.g., "2-10x improvement")
tags: prefix, technique, related-concepts
---
Reference files use the pattern: references/{prefix}-{slug}.md