Claude Code Advanced: Rebuilding AI Workflows with Skills

If you're a heavy Claude Code user, you've probably had this deja vu: every time you start a new project, Claude acts like a fresh intern who doesn't know anything.

You have to explain over and over: we use this coding style, the deploy process works like this, auth goes through that logic... Once is fine. Ten times? That's soul-crushing.

The old fix was CLAUDE.md. Dump all the rules in there, auto-load on startup. But as projects grow, that file gets bloated. I've seen CLAUDE.md files stuffed with so many prompts that Claude starts slow, wastes precious Context Window on pre-loaded content, and the scattered attention actually makes answers worse.

Anthropic's new Skills feature finally solves this elegantly. It's not just a feature -- it's a modular AI knowledge architecture that actually fits engineering intuition.

---

Core Architecture: Progressive Disclosure

This is probably the sexiest part of Skills design.

CLAUDE.md was all-or-nothing loading -- no matter what you asked, every rule got shoved into Context. Skills use a layered loading mechanism that Anthropic calls Progressive Disclosure.

Based on observation and official docs, it splits Context into three layers:

L1 Metadata (Metadata Layer)

On startup, only name and description of each Skill get loaded. Super lightweight (~100 tokens). Claude uses just this layer to route: does this question need a particular Skill?

L2 Instructions (Instructions Layer)

When Claude determines a Skill matches, it loads that Skill's SKILL.md body content (keep it under 5000 tokens).

L3 Resources (Resources Layer)

If SKILL.md references scripts or docs, those files are loaded on-demand.

Architecture Benefits

This means you can theoretically mount unlimited knowledge bases on Claude. As long as your Description is accurate, it only pulls knowledge when needed and never wastes idle Context. The description acts as the gate — idle skills cost zero context.

---

Hands-On: Building a Skill from Scratch

A standard Skill is just a self-contained directory. The structure looks a lot like a Node.js module or an Ansible Role.

Directory Structure

my-skill/
├── SKILL.md          # Core entry point (required)
├── scripts/          # Python or Bash scripts (optional)
├── references/       # Documentation and specs (optional)
└── assets/           # Static resource templates (optional)

Create a folder (e.g. my-skill) with a required SKILL.md file as the entry point. Optionally add scripts for Python/Bash, references for docs and specs, and assets for static templates.

SKILL.md Frontmatter Config

Strict format requirements here -- lessons learned from experience:

---
name: my-skill
description: When the user asks to commit code, use this Skill for code standards checking and commit workflow
allowed-tools: Read, Glob, Bash, Grep, Write
---
# Skill Title

Skill body content goes here...

Key gotchas:

1. name field: lowercase letters, numbers, and hyphens only. Must exactly match the directory name
2. description field: This is for the LLM's router. You need to clearly describe the trigger condition -- like "when user asks to commit code..." -- so Claude can match accurately

---

Skills vs MCP vs Custom Commands: How to Choose?

This is where confusion happens most. If MCP (Model Context Protocol) already exists, why do we need Skills? Here's the mental model:

Complementary Relationship

Don't think Skills will replace MCP. They're complementary.

Example: You write a Deploy Skill (brain) that tells Claude the deployment steps. During execution, Claude calls AWS MCP (hands) to actually operate the servers.

Skills (brain: knows how)
    ↓
    calls
    ↓
MCP (hands: actually does it)

---

6 Practical Skills Examples

These come from feiskyer/claude-code-settings and can be installed directly.

1. codex-skill - Codex CLI Automation

Delegates tasks to OpenAI Codex for GPT-5 series model scenarios.

Install:

/plugin marketplace add feiskyer/claude-code-settings
/plugin install codex-skill

Core features:

• Multiple execution modes (read-only, workspace write, full access)
• Model selection (gpt-5, gpt-5.1, gpt-5.1-codex)
• Approval-free autonomous execution
• JSON output support
• Resumable sessions

Prerequisite: Codex CLI (npm i -g @openai/codex or brew install codex)

---

2. autonomous-skill - Long-Running Task Automation

Executes complex long-running tasks across multiple sessions using dual-agent mode (Initializer + Executor).

Install:

/plugin install autonomous-skill

Core features:

• Dual-agent mode (Initializer creates task list, Executor completes tasks)
• Auto-continue across sessions with progress tracking
• Task isolation with independent directories (.autonomous/<task-name>/)
• Progress persistence via task_list.md and progress.md

Usage example:

You: "Please use autonomous skill to build a REST API for a todo app"
Claude: [Creates .autonomous/build-rest-api-todo/, initializes task list, starts executing]

---

3. nanobanana-skill - Gemini Image Generation

Uses Google Gemini API to generate or edit images.

Install:

/plugin install nanobanana-skill

Core features:

• Multiple aspect ratios (square, portrait, landscape, ultrawide)
• Image editing capability
• Multiple resolutions (1K, 2K, 4K)
• Supports gemini-3-pro-image-preview, gemini-2.5-flash-image

Prerequisites:

• Configure GEMINI_API_KEY in ~/.nanobanana.env
• Python3 + google-genai, Pillow, python-dotenv

---

4. youtube-transcribe-skill - YouTube Transcript Extraction

Extracts subtitles/transcripts from YouTube video links.

Install:

/plugin install youtube-transcribe-skill

Core features:

• Dual extraction: CLI (fast) and browser automation (fallback)
• Auto language selection (zh-Hans, zh-Hant, en)
• Efficient DOM extraction
• Saves transcripts to local text files

Prerequisite: yt-dlp (CLI method) or chrome-devtools-mcp (browser method)

---

5. kiro-skill - Interactive Feature Development

Idea-to-implementation interactive feature development workflow.

Install:

/plugin install kiro-skill

Trigger: Mention "kiro" or reference .kiro/specs/ directory

Workflow:

1. Requirements → Define what to build (EARS format + user stories)
2. Design → Determine how to build (architecture, components, data model)
3. Tasks → Create executable implementation steps (test-driven, incremental)
4. Execute → Implement tasks one by one

Usage example:

You: "I need to create a kiro feature spec for user authentication"
Claude: [Automatically uses kiro-skill]

---

6. spec-kit-skill - Spec-Driven Development

GitHub Spec-Kit integration for specification-based development.

Install:

/plugin install spec-kit-skill

Trigger: Mention "spec-kit", "speckit", "constitution", "specify" or reference .specify/ directory

Setup:

# Install spec-kit CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Initialize project
specify init . --ai claude

7-Phase Workflow:

1. Constitution → Establish governance principles
2. Specify → Define feature requirements
3. Clarify → Resolve ambiguities (max 5 questions)
4. Plan → Create technical strategy
5. Tasks → Generate dependency-ordered tasks
6. Analyze → Verify consistency (read-only)
7. Implement → Execute implementation

---

Practical Lessons Learned

Right now Claude Code is like a generalist -- knows a bit of everything but isn't an expert at anything. The essence of Skills is packaging domain expert know-how into self-contained, Docker-container-like packages.

Recommended Skill Categories

Best Practices

1. Write precise descriptions: This determines whether the Skill gets triggered correctly
2. Keep content under 5000 tokens: Too long hurts loading efficiency
3. Split by domain: One Skill, one domain
4. Reference external resources: Put complex content in references/ or scripts/

---

Summary

Skills are a major Claude Code upgrade. They solve the bloated CLAUDE.md and wasted Context problems, letting you:

• Modularly manage AI knowledge
• Load on demand to reduce token waste
• Trigger precisely to improve answer quality

If you're still rocking one massive CLAUDE.md, it's time to migrate to the Skills architecture.

---

Original author: AI Observatory | Published 2026-01-10