Agent-Skills.md

Agent Skills: Category Manager - Branch of JARVIS-01

Branch skill for building and improving categories. Use when creating new categories, validating category structure, improving existing categories, or migrating categories to new standard. Triggers: 'create category', 'improve category', 'validate category structure', 'fix category', 'category compliance', 'migrate category', 'JARVIS-XX structure', 'CLAUDE.md structure', 'settings.json format', 'self-improvement cycle'.

UncategorizedID: henmessi/plugin-dev/category-manager

Repository

henmessi/plugin-dev
Jarvis-Projects
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/Jarvis-Projects/plugin-dev/tree/HEAD/skills/category-manager

Skill Files

Browse the full folder contents for category-manager.

Download Skill

Loading file tree…

skills/category-manager/SKILL.md

Skill Metadata

Name
category-manager
Description
"Branch skill for building and improving categories. Use when creating new categories, validating category structure, improving existing categories, or migrating categories to new standard. Triggers: 'create category', 'improve category', 'validate category structure', 'fix category', 'category compliance', 'migrate category', 'JARVIS-XX structure', 'CLAUDE.md structure', 'settings.json format', 'self-improvement cycle'."

Category Manager - Branch of JARVIS-01

Build and improve categories following the category-management policy.

Policy Source

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

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

Quick Decision Tree

Task Received
    │
    ├── Create new category? ────────────> Workflow 1: Build
    │
    ├── Fix existing category? ──────────> Workflow 2: Improve
    │
    ├── Validate category? ──────────────> Validation Checklist
    │
    ├── Migrate to new standard? ────────> Workflow 3: Migrate
    │
    └── Self-improvement cycle? ─────────> Self-Improvement Process

Category Overview

Each JARVIS category maintains effective configuration through:

  • CLAUDE.md - Main Agent instructions at category root
  • .claude/settings.json - Tool permissions and MCP configurations
  • .claude/mcp.json - MCP server definitions (Execution layer)
  • .claude/skills/ - Primary Skill defining category policy
  • plugins/ - 4-Plugin Architecture

Workflow 1: Build New Category

Step 1: Determine Layer

| Range | Layer | Purpose | Example | |-------|-------|---------|---------| | 00-10 | Management | Build ecosystem infrastructure | JARVIS-07 MCP-Manager | | 11+ | Execution | Control external system | JARVIS-11 Cloudflare |

Decision criteria:

  • Does it build tools for OTHER categories? → Management
  • Does it control ONE external API/system? → Execution

Step 2: Assign Number

# Check existing categories
ls -d JARVIS-* | sort -t'-' -k2 -n
  • Management: Limited to 00-10, must be approved
  • Execution: Start from 11, take next available

Step 3: Create Full Structure

# Create all directories at once
mkdir -p JARVIS-XX-Name/{.claude/skills/[name]-management/references,plugins/{orchestrator,dev,bigquery-[name],category-[name]},TASKS}

Expected structure:

JARVIS-XX-Category-Name/
├── CLAUDE.md                        <- Category identity (REQUIRED)
├── .claude/
│   ├── settings.json                <- Tool permissions
│   ├── mcp.json                     <- MCP config (Execution layer)
│   └── skills/
│       └── [name]-management/       <- Primary Skill
│           ├── SKILL.md             <- REQUIRED
│           └── references/          <- Optional details
├── plugins/                         <- 4 Plugins (REQUIRED)
│   ├── orchestrator/                <- Shared - task routing
│   ├── dev/                         <- Shared - self-improvement
│   ├── bigquery-[name]/             <- Template - data access
│   └── category-[name]/             <- Unique - domain logic
└── TASKS/                           <- Task tracking
    └── TASK-XX-[name]/
        └── README.md

Step 4: Write CLAUDE.md

CLAUDE.md Structure

Minimal Template (for new categories):

# JARVIS-XX-CategoryName

## Role
[One sentence describing primary function]

## Responsibilities
- [Key responsibility 1]
- [Key responsibility 2]
- [Key responsibility 3]

## MCP Servers
| Server | Location | Purpose |
|--------|----------|---------|
| vault | VPS | Secrets management |
| supabase-common | CloudRun | Database access |

## Quick Reference
[Most common commands or patterns]

Full Template (for mature categories):

# JARVIS-XX-CategoryName

## Role
[Category's primary function and domain expertise]

## Responsibilities
- [Responsibility 1]
- [Responsibility 2]
- [Responsibility 3]

## MCP Servers
| Server | Location | Purpose |
|--------|----------|---------|
| server1 | VPS/CloudRun/Local | Description |

## Schemas (if database access)
| Schema | Purpose |
|--------|---------|
| schema1 | Description |

## Common Tasks

### Task Type 1
[Step-by-step instructions]

### Task Type 2
[Step-by-step instructions]

## Best Practices
- [Practice 1]
- [Practice 2]

## Integration Points
- **Category XX**: [How they interact]
- **Category YY**: [How they interact]

## Learnings
- [Learning 1 from previous conversations]
- [Learning 2]

## Changelog
- YYYY-MM-DD: [Change description]

CLAUDE.md Best Practices

  • Keep concise (500-2000 words ideal)
  • Use tables for structured data
  • Include practical examples
  • Update changelog on changes
  • Focus on actionable instructions

Management Layer Template:

# JARVIS-XX-CategoryName

## Role
[Category function] for the JARVIS AI Ecosystem.

## Responsibilities
- Define [domain] policy for all categories
- Maintain [domain] standards
- Support categories in [domain] tasks

## Integration
- **Plugin-dev branch**: [branch-name]
- **Primary Skill**: [skill-name]-management

## Quick Reference
[Most common operations for this category]

Execution Layer Template:

# JARVIS-XX-CategoryName

## Role
Control [External System] via MCP with full coverage.

## Responsibilities
- Manage [System] resources
- Automate [System] operations
- Monitor [System] status

## MCP Servers
| Server | Location | Coverage | Purpose |
|--------|----------|----------|---------|
| [name] | CloudRun | 90%+ | [Description] |

## Schemas (BigQuery)
| Schema | Purpose |
|--------|---------|
| jarvis_XX_[name] | [Data stored] |

## Quick Reference
[Most common MCP operations]

Step 5: Configure settings.json

Settings.json Location

.claude/settings.json in category root

Basic Structure

{
  "permissions": {
    "allow": [],
    "deny": []
  }
}

With MCP Servers

{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(git:*)",
      "mcp__vault__*"
    ],
    "deny": [
      "Bash(rm -rf:*)"
    ]
  },
  "mcpServers": {
    "vault": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-vault"],
      "env": {
        "VAULT_ADDR": "${VAULT_ADDR}"
      }
    }
  }
}

Permission Patterns

| Pattern | Meaning | |---------|---------| | Bash(npm:*) | Allow npm commands | | Bash(git:*) | Allow git commands | | mcp__server__* | Allow all tools from MCP server | | mcp__server__tool | Allow specific MCP tool | | Read(path/**) | Allow reading from path | | Write(path/**) | Allow writing to path |

Settings.json Best Practices

  • Follow least privilege principle
  • Document why permissions exist
  • Test after changes
  • Use environment variables for secrets
  • Keep MCP configs minimal

Step 6: Create Primary Skill

Follow skills-manager for full details. Minimum:

---
name: [category]-management
description: "This skill [function]. Use when [conditions]. Triggers: '[trigger1]', '[trigger2]'."
---

# [Category] Management - JARVIS-XX

[Core concept in 2-3 sentences]

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

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

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

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

Step 7: Set Up 4 Plugins

| Plugin | Action | |--------|--------| | orchestrator | Copy from shared source (identical) | | dev | Copy from shared source (identical) | | bigquery-[name] | Create from template, update table list | | category-[name] | Create custom with domain agents/skills |

Use plugins-manager for detailed plugin creation.

Step 8: Configure MCP (Execution Layer Only)

Work with JARVIS-07 to:

  1. Build or adapt MCP server
  2. Document all tools in Primary Skill
  3. Configure .claude/mcp.json
  4. Test tool coverage

Step 9: Validate

Run full validation checklist (see below).

Self-Improvement Cycle

Categories should run self-improvement periodically to maintain effectiveness.

When to Run

  • Every ~6 conversations
  • After completing major tasks
  • When issues or inefficiencies noticed
  • On explicit request

Self-Improvement Process

1. Analyze Current State
   ├── Read CLAUDE.md
   ├── Read settings.json
   └── Review recent patterns

2. Identify Improvements
   ├── Missing instructions
   ├── Outdated information
   ├── Permission gaps
   └── New learnings

3. Apply Changes
   ├── Update CLAUDE.md
   ├── Update settings.json
   └── Document changes

4. Validate
   ├── Test configurations
   └── Verify no breakage

What to Improve

CLAUDE.md:

  • Add instructions for recurring tasks
  • Remove outdated information
  • Improve clarity and organization
  • Add learnings from conversations
  • Update MCP server documentation

Settings.json:

  • Add permissions for frequently used tools
  • Remove unnecessary permissions
  • Update MCP configurations
  • Fix broken server configs

Self-Improvement Best Practices

  • Make incremental changes
  • Preserve working configurations
  • Document all changes
  • Test after modifications
  • Review periodically

Workflow 2: Improve Existing Category

Step 1: Analyze Current State

# Run category audit
ls -la JARVIS-XX-Name/
cat JARVIS-XX-Name/CLAUDE.md
cat JARVIS-XX-Name/.claude/skills/*/SKILL.md
ls JARVIS-XX-Name/plugins/

Step 2: Gap Analysis

| Component | Check | Common Issues | |-----------|-------|---------------| | CLAUDE.md | Exists? Up to date? | Missing MCP docs, outdated responsibilities | | Primary Skill | Complete? References? | Missing triggers, no validation checklist | | settings.json | Permissions correct? | Missing MCP tool permissions | | 4 Plugins | All present? | Missing plugin directories | | mcp.json | Configured? (Execution) | Wrong server URLs |

Step 3: Apply Fixes

Priority order:

  1. Critical: Missing CLAUDE.md or Primary Skill
  2. High: Missing plugins
  3. Medium: Outdated content
  4. Low: Formatting, clarity

Step 4: Document Changes

Create task record:

# TASK-XX-Category-Improvement

## Date: YYYY-MM-DD

## Changes Made
- [ ] Updated CLAUDE.md with [changes]
- [ ] Added missing [component]
- [ ] Fixed [issue]

## Validation
- [ ] All checks pass
- [ ] Tested functionality

Workflow 3: Migrate Category to New Standard

When category structure policy changes:

  1. Backup current state
  2. Compare with new standard (read Primary Skill)
  3. Create migration plan
  4. Apply changes incrementally
  5. Validate each step
  6. Document migration

Validation Checklist

Structure Checks

  • [ ] Directory named JARVIS-XX-Name (XX = 2-digit number)
  • [ ] Number matches layer (00-10 Management, 11+ Execution)
  • [ ] CLAUDE.md exists at root
  • [ ] CLAUDE.md has Role section
  • [ ] CLAUDE.md has Responsibilities section

Configuration Checks

  • [ ] .claude/settings.json exists and valid JSON
  • [ ] .claude/mcp.json exists (if Execution layer)
  • [ ] MCP servers documented in CLAUDE.md

Skill Checks

  • [ ] Primary Skill at .claude/skills/[name]-management/SKILL.md
  • [ ] SKILL.md has valid frontmatter (name, description)
  • [ ] Description has "Triggers:" section
  • [ ] references/ exists if SKILL.md > 1500 words

Plugin Checks

  • [ ] plugins/orchestrator/ exists
  • [ ] plugins/dev/ exists
  • [ ] plugins/bigquery-[name]/ exists
  • [ ] plugins/category-[name]/ exists
  • [ ] Each plugin has .claude-plugin/plugin.json

Integration Checks

  • [ ] If Management 01-06: branch exists in plugin-dev
  • [ ] If Execution: MCP configured and tested
  • [ ] TASKS/ directory exists

Common Issues & Fixes

| Issue | Diagnosis | Fix | |-------|-----------|-----| | Missing CLAUDE.md | ls JARVIS-XX/CLAUDE.md returns nothing | Create from template above | | Wrong layer number | Category 15 doing management work | Renumber or reassign responsibilities | | No Primary Skill | .claude/skills/ empty | Create following skills-manager | | Missing plugins | ls plugins/ shows < 4 dirs | Create missing plugin directories | | Outdated content | CLAUDE.md references old tools | Update with current MCP tools | | No mcp.json | Execution category without MCP | Work with JARVIS-07 to create |

BigQuery Integration (Optional)

Categories can track metrics in BigQuery for analytics and improvement:

bigquery.jarvis_analytics.
├── jarvis_XX_conversations    # Conversation logs
├── jarvis_XX_improvements     # Improvement history
└── jarvis_XX_metrics          # Performance metrics

Tracked Metrics

  • Conversation count
  • Task types and frequency
  • Error patterns
  • Improvement effectiveness

Use bigquery-[name] plugin for data access.

When to Use This Skill

  • User asks to create a new JARVIS category
  • User asks to validate category compliance
  • User asks to fix category structure issues
  • User asks about CLAUDE.md structure or settings.json format
  • User asks about self-improvement cycle
  • DEV-Manager detects category problems during improvement cycle
  • Migrating categories to updated standard
  • Regular improvement cycle (~6 sessions)

Sync Protocol

Before executing any workflow:

  1. Read JARVIS-01's category-management SKILL.md
  2. Check for policy updates
  3. Apply current policy, not cached knowledge
Category Manager - Branch of JARVIS-01 Skill | Agent Skills