When to Use Claude Code Skills vs Commands vs Agents

Ever since Anthropic released Skills I’ve been thinking about how to optimize my Personal AI Infrastructure using the proper hierarchy.

My thoughts have been guided by this type of language used by Anthropic.

Skills leverage Claude’s VM environment to provide capabilities beyond what’s possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you’d create for a new team member.From the Anthropic Documentation

Ever since reading that I’ve been thinking about how could / should modify my entire structure, so I asked Kai (my Claude Code-based assistant) to do a full analysis of our current system architecture as compared to my new, supposedly ideal state, and compared to the official documentation from Anthropic on how to use Skills, and here’s that proposal and Kai’s analysis of it.

I find the analysis super interesting. And yes, I ended up redoing my entire PAI structure based on this. With my whole system now following this Skills-first model.

Here’s what the overall structure looks like:

~/.claude/
├── skills/                    # Domain containers
│   ├── blogging/
│   │   ├── SKILL.md          # Main prompt file with routing logic
│   │   ├── workflows/        # Commands live here
│   │   │   ├── write.md
│   │   │   ├── publish.md
│   │   │   └── rewrite.md
│   │   └── context/          # Supporting prompt files by topic
│   │       ├── formatting.md # Frontmatter and structure
│   │       └── examples.md   # Sample blog posts
│   ├── research/
│   │   ├── SKILL.md          # Main prompt file
│   │   ├── workflows/
│   │   │   └── conduct.md
│   │   └── context/          # Supporting prompts
│   │       ├── sources.md    # Preferred research sources
│   │       └── methodology.md
│   └── images/
│       ├── SKILL.md          # Main prompt file
│       ├── workflows/
│       │   └── generate.md
│       └── context/          # Supporting prompts
│           ├── styles.md     # Image style guidelines
│           └── prompts.md    # Prompt templates
├── agents/                    # Parallel workers
│   ├── engineer.md
│   ├── architect.md
│   ├── pentester.md
│   ├── researcher.md
│   └── intern.md
├── commands/                  # System-level only
│   ├── update-kai-repo.md
│   └── check-cc-updates.md
└── history/                   # Logging output
    ├── sessions/
    ├── research/
    └── learnings/

First let’s start with the basic idea I started with after reading Anthropic’s documentation.

I think Skills are more Containers for all previous primitives. Commands aren’t more prompt than Skills are. In fact I think Skills are BETTER prompts because they can be modular.

You can have the core content in the main SKILL.md file and then have that branch within the directory to other supplemental files that load if needed.

To me the breakdown is:

Skill is the Container for a topic / area you want competence in

Command is for tasks within those areas

Agents are for parallelization where you don’t need the output afterwards (although I log everything from them too to the FS)

MCPs I’m still a bit more confused about because it feels like direct API code within a skill / command / or agent is better than an MCP

So for Agents I have them call skills usually, or commands if the task is discrete enough. Commands for discrete pieces of work. And Skills for the meta containers for a collection of different tasks I might want to do around that area.

For example, I have a Blogging skill. And inside that I have write-blog.md which takes raw text and puts it in my frontmatter / formatting and starts my dev server and opens it in Chrome. And also Publish-blog.md which checks for spelling and changes draft to published and pushes.

Importantly, I can just say the words “write a blog” or “publish a blog”, and it automatically loads that skill and the correct workflow within the skill which may or may not use commands or do it directly in the skill prompt.

Last piece there is that some Skills and the commands within them, automatically spin up agents to do that work, and all my agents are also dumping their context to the filesystem under /history/sub/sub/ for full logging.

The following is my (Kai’s) analysis of Daniel’s PAI nesting system using Skills as the routing and logical centerpiece:

Current State Problems

Looking at the PAI architecture, I found three major issues:

Problem 1: Commands living outside skills

~/.claude/commands/write-blog.md       # 721 lines
~/.claude/commands/publish-blog.md     # 471 lines
~/.claude/skills/blogging/SKILL.md     # 48KB

These commands should be INSIDE the blogging skill as workflows, not floating in a global namespace.

Problem 2: Duplication

~/.claude/skills/get-ai-news/SKILL.md      # 12KB
~/.claude/commands/get-ai-news.md          # 300 lines

Why both? Pick one. The skill version should be authoritative.

Problem 3: Monolithic skills

Blogging SKILL.md was 48KB doing everything:

• Writing workflows
• Publishing workflows
• Voice guidelines
• Formatting rules
• Image workflows

Should be modular with subdirectories.

The Correct Three-Tier Hierarchy

Based on Daniel’s philosophy, here’s how it should work:

Tier 1: Skills (Domain Containers)

Skills are self-contained modules. Everything for a domain lives inside.

Structure:

~/.claude/skills/[skill-name]/
├── SKILL.md              # Routing logic
├── workflows/            # Tasks within domain
│   ├── task1.md
│   └── task2.md
├── context/              # Knowledge base
│   └── reference.md
└── examples/             # Templates
    └── sample.md

Example (Blogging):

skills/blogging/
├── SKILL.md
├── workflows/
│   ├── write.md
│   ├── publish.md
│   └── canonicalize.md
├── voice/
│   └── daniels-voice.md
└── formatting/
    └── frontmatter.md

Tier 2: Commands (Internal Workflows)

Commands are NOT separate global functions. They’re workflows INSIDE skills.

When you say “write a blog post”:

1. Blogging skill loads (keyword match)
2. SKILL.md analyzes intent → “write”
3. Routes to workflows/write.md internally
4. Workflow executes

No global command needed.

Global commands should only be:

• System-level operations (initialization, state)
• Cross-skill orchestration
• Meta-operations on PAI itself

Domain work belongs in domain containers.

Tier 3: Agents (Parallel Workers)

Agents are correctly separated. They’re for parallelization.

Located at ~/.claude/agents/ and invoked by skills/commands when you need concurrent execution.

What I Found Wrong

Example 1: Blogging Skill

Before (wrong):

Global namespace:
  commands/write-blog.md
  commands/publish-blog.md
  commands/rewrite-blog.md

Skill directory:
  skills/blogging/SKILL.md (48KB monolith)

After (correct):

skills/blogging/
├── SKILL.md (routing, 5-10KB)
└── workflows/
    ├── write.md
    ├── publish.md
    └── rewrite.md

When you say “write a blog”, the skill loads and routes internally to workflows/write.md.

Example 2: Research Skill

Before:

commands/conduct-research.md
skills/research/SKILL.md

After:

skills/research/
├── SKILL.md
└── workflows/
    └── conduct.md

Example 3: Get AI News

Before (duplication):

skills/get-ai-news/SKILL.md
commands/get-ai-news.md

After:

skills/get-ai-news/
└── SKILL.md

Delete the duplicate command.

Key Insights

Insight 1: Skills ARE Containers

Not “skills that call commands” but “skills that CONTAIN workflows.”

This is encapsulation. Related functionality belongs together.

Insight 2: Intent-Based Routing

User says “write a blog” → Skill loads → SKILL.md routes to workflows/write.md → Executes.

The routing happens INSIDE the skill based on natural language intent.

Insight 3: Modular Beats Monolithic

Breaking 48KB blogging SKILL.md into:

• SKILL.md (routing logic)
• workflows/ (individual tasks)
• voice/ (voice guidelines)
• formatting/ (format rules)

Much easier to maintain.

Insight 4: Global Commands Should Be Minimal

~/.claude/commands/ is for system utilities, not domain work.

Think of it like /usr/bin/ – system tools only.

Insight 5: This is OOP

Skill = Class Workflows = Methods Context = Properties

Don’t scatter methods globally. Encapsulate in the class.

Insight 6: Anthropic Was Right

The Skills-as-Containers pattern from Anthropic’s October 2025 release is the correct architecture.

Implementation Roadmap

I recommended this phased approach:

Phase 1: Prove the Concept

Restructure one skill (blogging) completely:

1. Create workflows/, voice/, formatting/ directories
2. Move commands into workflows/
3. Update SKILL.md routing logic
4. Test: “write a blog” should work
5. Delete old commands

Phase 2: Extend to Core Skills

Apply pattern to:

• Research skill
• Images skill
• Email skill
• Development skill

Phase 3: Audit Everything

What’s left in commands/:

• System-level? Keep
• Domain-specific? Move to skill
• Deprecated? Delete

Goal: <15 files in commands/, all system-level.

Phase 4: Document

Create:

• Skill development guide
• Template structure
• Migration guide
• Best practices

Visual Comparison

Before (problematic):

skills/blogging/SKILL.md (48KB, does everything)
commands/write-blog.md (floating separate)
commands/publish-blog.md (floating separate)
commands/rewrite-blog.md (floating separate)

Issues:

• Commands divorced from context
• Skills not self-contained
• Unclear invocation path
• Duplication possible

After (aligned):

skills/blogging/
├── SKILL.md (routing logic, 5-10KB)
└── workflows/
    ├── write.md
    ├── publish.md
    └── rewrite.md

Benefits:

• Self-contained and portable
• Clear hierarchy
• No duplication
• Intent-based routing
• Easy to see what’s available

MCPs vs Direct Code

I agree with Daniel’s intuition. Use MCPs when:

• Third-party service you don’t control
• Reusable across multiple contexts
• MCP already exists and works well

Build directly when:

• Custom PAI functionality
• Tight workflow integration
• Want full control

Direct API code in a skill/command/agent is often better than adding an MCP layer.

Implementation Results

We implemented these changes:

Blogging Skill:

• Created workflows/, voice/, formatting/ directories
• Moved write-blog.md, publish-blog.md, rewrite-blog.md into workflows/
• Skill now self-contained

Research Skill:

• Created workflows/ directory
• Moved conduct-research.md into workflows/

Images Skill:

• Created workflows/ directory
• Moved create-custom-image.md into workflows/

Video Skill:

• Created workflows/ directory
• Moved create-custom-video.md into workflows/

Cleanup:

• Deleted duplicate get-ai-news command

Documentation:

• Created SKILL-DEVELOPMENT-GUIDE.md with templates, examples, best practices

Git History

Two commits document the transformation:

Commit 1 (f93187f): Pre-upgrade checkpoint

• 276 files changed
• Captures state before changes

Commit 2 (6899279): v1.1.0 restructuring

• 11 files changed, 3.5K insertions
• Implements Skills-as-Containers

Success Metrics

All changes committed and pushed. PAI now follows proper hierarchy:

• Skills are true containers
• Commands are internal workflows
• Agents handle parallelization
• Clear pattern for future development

Conclusion

Daniel’s philosophy is correct: Skills are containers, commands are workflows inside them, agents are workers.

The key realization: Skills don’t CALL commands, they CONTAIN workflows.

Get the hierarchy right and your PAI system becomes:

• More maintainable
• More discoverable
• More portable
• More scalable