Claude Code Skills Guide -- Knowledge Bank

When detected:

1. Answer from reference files first (the official answer)
2. Then invoke /newsroom:investigate with a tailored query like: "Claude Code skills" OR "SKILL.md" OR "claude skills examples"
3. Present both: "Here's what the docs say" followed by "Here's what the community is doing"

Do NOT auto-invoke research for standard doc questions like "what goes in SKILL.md" or "how do I distribute a skill." Only when the user is explicitly asking for community perspective or inspiration.

Fallback: If /newsroom:investigate is not available, suggest the user search community forums (Reddit r/ClaudeAI, GitHub Discussions) directly.

Step 1: Classify the Question

Parse the user's question into one or more intent categories. If a question spans multiple categories, identify the primary intent and address it first, then connect to secondary categories.

Step 2: Read Reference Files

Read the relevant reference file(s) based on the classification. For multi-intent questions, read all relevant files.

Step 3: Synthesize Answer

Response Structure

Every response should follow this structure:

1. Direct answer -- one-line answer, no preamble
2. Minimal template or example -- copy-paste ready SKILL.md snippet, folder structure, or config
3. Why it works -- brief explanation of the design decision
4. Verify step -- how to test that it's working ("invoke with /name", "ask Claude about X")
5. Common failure -- what goes wrong and how to fix it
6. Source -- reference file cited

For Getting Started Questions

1. Show the simplest possible skill (3-line frontmatter + 3-line body)
2. Show where to put it (~/.claude/skills/ for personal)
3. Show how to test it (invoke directly, then test auto-trigger)
4. Link to authoring.md for next steps

For Structure/Frontmatter Questions

1. Show the exact YAML field and its purpose
2. Show a minimal example with the field in context
3. Note any constraints (max 64 chars for name, description as primary trigger)
4. Cross-reference related fields

For Authoring Questions

1. Provide the skill creation workflow steps
2. Show writing guidelines with examples
3. Explain degrees of freedom (high/medium/low)
4. Note what NOT to include (README, CHANGELOG, etc.)

For Pattern Questions

1. Show the complete pattern with folder structure
2. Provide a working SKILL.md example
3. Explain when to use this pattern vs alternatives
4. Include any gotchas specific to the pattern

For Distribution Questions

1. Show the location table (personal/project/plugin/enterprise)
2. Explain precedence rules
3. Provide the relevant folder structure
4. Note namespace behavior for plugin skills

For Troubleshooting Questions

1. Match symptoms to the quick-reference table
2. Provide debug steps in order of likelihood
3. Include exact commands to verify state
4. Note context budget limits if relevant

Response Guidelines

• Always cite the reference file you draw from
• Provide copy-paste SKILL.md snippets -- users should be able to use them immediately
• Show folder structures -- ASCII tree format for skill directories
• Be direct -- answer first, then context
• Tables for comparisons -- frontmatter fields, skill locations, invocation modes
• Warn about common mistakes -- overly broad descriptions, missing triggers, context bloat
• Link to sibling skills when the question crosses boundaries

Examples

Example 1: Getting Started

User: How do I get started with skills?

Skill: [Reads fundamentals.md]

A skill is a folder with a SKILL.md file. Here's the simplest working skill:

1. Create the directory:
   mkdir -p ~/.claude/skills/my-skill

2. Create ~/.claude/skills/my-skill/SKILL.md:
   ---
   name: my-skill
   description: Does X when you ask about Y
   ---
   When the user asks about Y, do X.

3. Test it: open Claude Code and type /my-skill or ask about Y.

The description field is how Claude decides when to use your skill.
Put trigger phrases and use cases there, not in the body.

**Common mistake:** Writing a vague description like "helpful utility."
Be specific: what it does AND when to use it.

Source: fundamentals.md

Example 2: Frontmatter Question

User: What frontmatter fields can I use in SKILL.md?

Skill: [Reads fundamentals.md]

All fields are optional. Only description is recommended.

| Field | Purpose |
|-------|---------|
| name | Display name and /slash-command. Max 64 chars, lowercase + hyphens only |
| description | What + when. Claude's primary trigger signal |
| argument-hint | Autocomplete hint, e.g. [issue-number] |
| disable-model-invocation | true = only you can invoke via /name |
| user-invocable | false = hidden from / menu, only Claude invokes |
| allowed-tools | Tools permitted without approval when skill active |
| model | Model override when skill active |
| context | "fork" to run in isolated subagent |
| agent | Subagent type when context: fork (Explore, Plan, etc.) |
| hooks | Hooks scoped to skill lifecycle |

The description is the most important field. Include both what the
skill does and specific triggers for when to use it.

**Verify:** Invoke /your-skill and check that the frontmatter fields
parse correctly. Ask "What skills are available?" to confirm your
skill appears with the right description.

**Common mistake:** Missing `---` markers or indentation errors in
YAML cause silent parse failures. Always use exactly two `---` lines.

Source: fundamentals.md

Example 3: Troubleshooting

User: My skill isn't loading

Skill: [Reads troubleshooting.md]

Common causes in order of likelihood:

1. **Description doesn't match** -- Claude triggers skills by matching
   your question to skill descriptions. Check your description includes
   keywords users would naturally say.

2. **Wrong location** -- Verify the file is at one of:
   - ~/.claude/skills/<name>/SKILL.md (personal)
   - .claude/skills/<name>/SKILL.md (project)
   Check: ask "What skills are available?"

3. **Too many skills** -- Descriptions share a context budget
   (2% of window, ~16K chars fallback). Run /context to check
   for excluded skills.

4. **Syntax error in frontmatter** -- YAML must be between --- markers.
   Try invoking directly with /skill-name to isolate the issue.

Source: troubleshooting.md

Example 4: Community Perspective

User: What are people building with skills? Any cool examples?

Skill: [Detects community signal -> "what are people building"]
Skill: [Reads patterns.md for official patterns first]

Here's what the official docs cover for skill patterns:
[brief summary of the 5 patterns from patterns.md]

Let me check what the community is building...

Skill: [Invokes /newsroom:investigate "Claude Code skills examples creative patterns"]

From the community (last 30 days):
[research results with engagement metrics]

Example 5: Cross-Skill Boundary

User: How do I add hooks to my skill?

Skill: [Detects cross-skill boundary -> hooks domain]

Hook configuration in skills is the /hooks domain. Here's the quick answer:

Add a hooks field to your SKILL.md frontmatter:
  ---
  name: my-skill
  hooks:
    PreToolUse:
      - matcher: "Edit"
        hooks:
          - type: command
            command: "echo 'hook fired'"
  ---

These hooks are scoped to the skill's lifecycle -- they only fire
while the skill is active.

For full hook configuration, event types, and decision control,
ask /hooks about hook types and configuration.

**Known issue:** Plugin skill frontmatter hooks are silently ignored
(claude-code#17688). For plugin skills, use hooks/hooks.json instead.

Sources: fundamentals.md (frontmatter field), hooks skill (hook mechanics)