Claude Skills Project Configuration

Claude Skills Project Configuration

This file governs Claude's behavior when working on the claude-skills repository.

---

Skill Authorship Standards

Skills follow the [Agent Skills specification](https://agentskills.io/specification). This section covers project-specific conventions that go beyond the base spec.

The Description Trap

**Critical:** Never put process steps or workflow sequences in descriptions. When descriptions contain step-by-step instructions, agents follow the brief description instead of reading the full skill content. This defeats the purpose of detailed skills.

Brief capability statements (what it does) and trigger conditions (when to use it) are both appropriate. Process steps (how it works) are not.

**BAD - Process steps in description:**

description: Use for debugging. First investigate root cause, then analyze
patterns, test hypotheses, and implement fixes with tests.

**GOOD - Capability + trigger:**

description: Diagnoses bugs through root cause analysis and pattern matching.
Use when encountering errors or unexpected behavior requiring investigation.

**Format:** `[Brief capability statement]. Use when [triggering conditions].`

Descriptions tell WHAT the skill does and WHEN to use it. The SKILL.md body tells HOW.

---

Frontmatter Requirements

Per the [Agent Skills specification](https://agentskills.io/specification), only `name` and `description` are top-level required fields. Custom fields go under `metadata`.

---
name: skill-name-with-hyphens
description: [Brief capability statement]. Use when [triggering conditions] - max 1024 chars
license: MIT
metadata:
  author: https://github.com/Jeffallan
  version: "1.0.0"
  domain: frontend
  triggers: keyword1, keyword2, keyword3
  role: specialist
  scope: implementation
  output-format: code
  related-skills: fullstack-guardian, test-master, devops-engineer
---

**Top-level fields (spec-defined):**

• name: Letters, numbers, and hyphens only (no parentheses or special characters)
• description: Maximum 1024 characters. Capability statement + trigger conditions. No process steps.
• license: Always MIT for this project
• allowed-tools: Space-delimited tool list (only on skills that restrict tools)

**Metadata fields (project-specific):**

• author: GitHub profile URL of the skill author
• version: Semantic version string (quoted, e.g., "1.0.0")
• domain: Category from the domain list below
• triggers: Comma-separated searchable keywords
• role: specialist | expert | architect | engineer
• scope: implementation | review | design | system-design | testing | analysis | infrastructure | optimization | architecture
• output-format: code | document | report | architecture | specification | schema | manifests | analysis | analysis-and-code | code+analysis
• related-skills: Comma-separated skill directory names (e.g., `fullstack-guardian, test-master