Skills Manager - Branch of JARVIS-04

Build and improve skills following the skills-management policy.

Policy Source

Primary policy: JARVIS-04 → .claude/skills/skills-management/SKILL.md

This branch executes the policy defined by JARVIS-04. Always sync with Primary before major operations.

Quick Decision Tree

Task Received
    │
    ├── Create new skill? ───────────────> Workflow 1: Build
    │   └── What type?
    │       ├── Primary (JARVIS-XX) ─────> Full policy skill
    │       ├── Branch (plugin-dev) ─────> Execution skill
    │       └── Domain (category) ───────> Domain knowledge skill
    │
    ├── Adapt marketplace skill? ────────> Workflow 3: Adapt
    │
    ├── Fix existing skill? ─────────────> Workflow 2: Improve
    │
    └── Validate skill? ─────────────────> Validation Checklist

Skill Overview

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools.

What Skills Provide:

• Specialized workflows - Multi-step procedures for specific domains
• Tool integrations - Instructions for working with specific file formats or APIs
• Domain expertise - Company-specific knowledge, schemas, business logic
• Bundled resources - Scripts, references, and assets for complex tasks

Skill Structure

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash)
    ├── references/       - Documentation loaded as needed
    ├── examples/         - Working code examples
    └── assets/           - Files used in output (templates, icons)

Progressive Disclosure Principle

Skills use a three-level loading system to manage context efficiently:

Level	Content	When Loaded	Size Target
1. Metadata	name + description	Always in context	~100 words
2. SKILL.md body	Main instructions	When skill triggers	<2000 words
3. Bundled resources	Details, examples, scripts	As needed by Claude	Unlimited

What Goes Where:

Content Type	Location	Loaded
Core concepts, overview	SKILL.md	On trigger
Essential procedures	SKILL.md	On trigger
Quick reference tables	SKILL.md	On trigger
Detailed patterns	references/	On demand
Advanced techniques	references/	On demand
API documentation	references/	On demand
Working code examples	examples/	On demand
Utility scripts	scripts/	Executed
Templates, assets	assets/	Used in output

Skill Types

Type	Location	Purpose	Content Focus
Primary	JARVIS-XX/.claude/skills/	Define policy	What and why
Branch	plugin-dev/skills/	Execute policy	How to do
Domain	plugin-category/skills/	Domain knowledge	Specific guidance

Workflow 1: Build New Skill

Step 1: Understand the Skill Purpose

Answer these questions:

• What functionality should this skill support?
• What triggers should invoke this skill?
• What procedural knowledge does Claude need?
• What scripts, references, or examples would be helpful?

Step 2: Determine Skill Type

Question	Answer → Type
Defines policy for JARVIS?	Primary skill
Executes policy from Primary?	Branch skill
Provides domain knowledge?	Domain skill

Step 3: Write Frontmatter

---
name: skill-name
description: "This skill [does what]. Use when [conditions]. Triggers: '[trigger1]', '[trigger2]', '[trigger3]'."
---

Description Requirements:

• Third-person format: "This skill should be used when..."
• "Use when" clause: Specific conditions for triggering
• "Triggers:" section: 3+ terms in single quotes
• Specific phrases: Exact words users would say

Good example:

description: "This skill should be used when the user asks to 'create a hook', 'add a PreToolUse hook', 'validate tool use', or mentions hook events (PreToolUse, PostToolUse, Stop)."

Bad examples:

# Wrong: Vague, no triggers
description: "Provides hook guidance."

# Wrong: Not third person
description: "Use this skill when working with hooks."

# Wrong: Missing trigger phrases
description: "Load when user needs hook help."

Step 4: Choose Content Pattern

Pattern 1: Policy Skill (Primary)

---
name: [domain]-management
description: "This skill defines [domain] policy for JARVIS. Use when [conditions]. Triggers: '[trigger1]', '[trigger2]', '[trigger3]'."
---

# [Domain] Management - JARVIS-XX

[Core concept in 2-3 sentences explaining what this policy covers]

## Core Concept
[What this domain is about, key principles]

## When to Use This Skill
- [Condition 1]
- [Condition 2]
- [Condition 3]

## Key Structures
[Tables, diagrams, templates]

## Workflows
### Workflow 1: [Name]
1. [Step]
2. [Step]

### Workflow 2: [Name]
1. [Step]
2. [Step]

## Validation Checklist
- [ ] [Check 1]
- [ ] [Check 2]

## Reference Files
- [references/detail.md](references/detail.md) - [Description]

Pattern 2: Execution Skill (Branch)

---
name: [domain]-manager
description: "Branch skill for [action]. Use when [conditions]. Triggers: '[trigger1]', '[trigger2]'."
---

# [Domain] Manager - Branch of JARVIS-XX

[What this branch executes]

## Policy Source
**Primary policy**: JARVIS-XX → `.claude/skills/[domain]-management/SKILL.md`

## Quick Decision Tree
[ASCII diagram for routing]

## Workflow 1: [Name]
### Step 1: [Action]
[Details]

### Step 2: [Action]
[Details]

## Validation Checklist
- [ ] [Check 1]
- [ ] [Check 2]

## Common Issues & Fixes
| Issue | Fix |
|-------|-----|
| [Problem] | [Solution] |

## Sync Protocol
[How to sync with Primary]

Pattern 3: Domain Skill

---
name: [domain]
description: "Domain knowledge for [area]. Use when [conditions]. Triggers: '[trigger1]', '[trigger2]'."
---

# [Domain] Knowledge

## Overview
[What this domain covers]

## Key Concepts
### [Concept 1]
[Explanation]

## Common Operations
```bash
[Example command or code]

Best Practices

• [Practice 1]
• [Practice 2]

Troubleshooting

Issue	Solution
[Problem]	[Fix]

### Step 5: Write Main Content

**Word limit**: Under 2000 words

**Writing style**: Imperative form ("Create...", "Validate...", "Check...")

**Required sections:**
1. Title with context (e.g., "- Branch of JARVIS-XX")
2. Core concept or Policy Source
3. When to Use (Primary) or Quick Decision Tree (Branch)
4. Main workflows with numbered steps
5. Validation Checklist
6. Reference Files (if references/ exists)

### Step 6: Create Bundled Resources (if needed)

**scripts/** - Executable utilities:

```bash
# When to include: Same code rewritten repeatedly
# Example: scripts/validate-skill.sh
# Benefits: Token efficient, deterministic

references/ - Detailed documentation:

# When to include: Content that would bloat SKILL.md
# Examples: references/patterns.md, references/advanced.md
# Benefits: Loaded only when needed

examples/ - Working code:

# When to include: Complete, runnable examples
# Examples: examples/hook-example.sh
# Benefits: Users can copy and adapt

assets/ - Output files:

# When to include: Files used in output
# Examples: assets/template.json, assets/logo.png
# Benefits: Used without loading into context

Step 7: Validate

Run full validation checklist.

Workflow 2: Improve Existing Skill

Step 1: Analyze Current State

# Read skill
cat skills/[name]/SKILL.md

# Check word count
wc -w skills/[name]/SKILL.md

# Check references
ls skills/[name]/references/

Step 2: Gap Analysis

Component	Check	Common Issues
name	lowercase-hyphens?	Spaces, uppercase
description	Third person?	"Use this skill when..."
description	Has triggers?	Missing "Triggers:" section
description	Has "Use when"?	Only describes, no conditions
content	Under 2000 words?	Too long, needs references/
content	Imperative style?	"You should...", passive voice
references	Exists if needed?	Long content without references/

Step 3: Apply Fixes

Fixing description format:

Before (wrong):

description: "Use this skill when working with hooks."

After (correct):

description: "This skill should be used when the user asks to 'create a hook', 'validate hooks', or mentions PreToolUse/PostToolUse events. Triggers: 'create hook', 'hook validation', 'PreToolUse'."

Converting to imperative:

Before (wrong):

You should start by reading the configuration file.
The skill is used to create hooks.

After (correct):

Start by reading the configuration file.
Create hooks following these steps.

Moving content to references:

1. Identify sections > 500 words
2. Create references/[section].md
3. Move content
4. Add link: See [references/section.md](references/section.md)

Adding comparison tables:

| Option | Pros | Cons | Use When |
|--------|------|------|----------|
| [A] | [+] | [-] | [Condition] |
| [B] | [+] | [-] | [Condition] |

Adding ASCII diagrams:

Task Received
    │
    ├── Condition A? ──> Action 1
    │
    └── Condition B? ──> Action 2

Step 4: Validate

Run full validation checklist.

Workflow 3: Adapt Marketplace Skill

When taking a skill from wshobson-agents, obra-superpowers, or similar:

Step 1: Read Original Skill

cat marketplace-plugin/skills/[skill]/SKILL.md
ls marketplace-plugin/skills/[skill]/references/

Note:

• Writing patterns used
• Content organization
• Triggers format
• Reference structure

Step 2: Identify JARVIS Fit

Original Focus	JARVIS Target
Generic orchestration	plugin-orchestrator skill
Self-improvement	plugin-dev branch skill
Data/analytics	Plugin-BigQuery skill
Domain-specific	Plugin-Category skill

Step 3: Adapt Description

Original (generic):

description: "Build production-ready monitoring..."

Adapted (JARVIS-specific):

description: "This skill should be used when setting up monitoring for JARVIS categories, tracking MCP server metrics, or implementing category alerting. Triggers: 'monitoring', 'observability', 'metrics', 'alerts'."

Step 4: Add JARVIS Context

For Primary skills:

## When to Use This Skill
- Creating monitoring for new JARVIS category
- Setting up MCP server observability
- Implementing cross-category metrics
- Configuring JARVIS-00 dashboards

For Branch skills:

## Policy Source
**Primary policy**: JARVIS-XX → `.claude/skills/[domain]-management/SKILL.md`

Step 5: Adapt Content

• Replace generic examples with JARVIS examples
• Add references to JARVIS tools (MCP, BigQuery)
• Include category-specific workflows
• Update validation to include JARVIS checks

Step 6: Validate Adaptation

Run full validation checklist.

Skill Auto-Discovery

Claude Code automatically discovers skills:

1. Scans skills/ directory in plugin
2. Finds subdirectories containing SKILL.md
3. Loads skill metadata (name + description) always
4. Loads SKILL.md body when skill triggers
5. Loads references/examples as needed

Skill locations:

Location	Scope
plugin/skills/	Available when plugin installed
.claude/skills/	Available in project
~/.claude/skills/	Available in all projects

Validation Checklist

Structure

• File is SKILL.md in skill subdirectory
• Skill directory follows kebab-case naming
• Referenced files actually exist

Frontmatter

• Valid YAML between --- markers
• name: lowercase, hyphens, 3-50 characters
• description: uses third person ("This skill should be used when...")
• description: has "Use when" clause with conditions
• description: has "Triggers:" with 3+ specific terms

Content

• Title with context (e.g., "- Branch of JARVIS-XX")
• Core concept or Policy Source section
• Main content under 2000 words
• Imperative writing style throughout (not "You should...")
• Numbered steps for workflows
• Validation Checklist section
• References to bundled resources if they exist

Bundled Resources (if applicable)

• references/ exists if content > 1500 words
• No duplicate content between SKILL.md and references/
• Links to references work
• Scripts are executable
• Examples are complete and runnable

Integration

• No conflicts with other skills in same plugin
• References JARVIS patterns where relevant

Writing Best Practices

DO:

• ✅ Use third person in description ("This skill should be used when...")
• ✅ Include specific trigger phrases ("'create hook'", "'validate'")
• ✅ Use imperative form in body ("Create...", "Validate...", "Check...")
• ✅ Keep SKILL.md under 2000 words
• ✅ Move detailed content to references/
• ✅ Include comparison tables for options
• ✅ Provide ASCII diagrams for complex flows
• ✅ Link to references for detailed content
• ✅ Include "Common Issues & Fixes" table

DON'T:

• ❌ Use second person ("You should...", "You can...")
• ❌ Have vague triggers ("Provides guidance")
• ❌ Exceed 2000 words in SKILL.md
• ❌ Duplicate content between files
• ❌ Leave procedures vague ("do the thing")
• ❌ Skip validation checklists
• ❌ Include broken examples

Common Issues & Fixes

Issue	Diagnosis	Fix
Skill not triggering	Vague description	Add specific "Triggers:" terms
Wrong person	"Use this skill when..."	Use "This skill should be used when..."
No triggers	Description lacks "Triggers:"	Add comma-separated trigger terms
Too long	SKILL.md > 2000 words	Move details to references/
Passive voice	"is used to", "should be"	Rewrite with imperative verbs
Vague steps	"configure the thing"	Add numbered, specific steps
Missing checklist	No validation section	Add checkbox list
No examples	Procedures without examples	Add code blocks, templates
Duplicate content	Same info in SKILL.md and references	Keep in one place only

When to Use This Skill

• User asks to create a new skill
• User asks to adapt a marketplace skill
• User asks to validate skill structure
• User asks to improve skill content or description
• User asks about progressive disclosure or references
• DEV-Manager detects skill issues during improvement cycle
• Regular improvement cycle (~6 sessions)

Sync Protocol

Before executing any workflow:

1. Read JARVIS-04's skills-management SKILL.md
2. Check for policy updates
3. Apply current policy, not cached knowledge