InkdownInkdown
Start writing

Claude-Code

62 files·4 subfolders

Shared Workspace

Claude-Code
codex

09-skills-plugins

Shared from "Claude-Code" on Inkdown

Skills & Plugins Architecture

Overview

Skills and Plugins extend Claude Code's capabilities. Skills are user-defined prompts and workflows. Plugins are code extensions that add tools and commands.

Plain text
┌─────────────────────────────────────────────────────────────────────────────┐
│                    SKILLS & PLUGINS ARCHITECTURE                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         SKILLS                                      │   │
│  │                                                                     │   │
│  │  User-defined prompts and workflows                                 │   │
│  │                                                                     │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐              │   │
│  │  │  Commit  │  │  Review  │  │  PR      │  │ Custom   │              │   │
│  │  │  Skill   │  │  Skill   │  │  Skill   │  │ Skills   │              │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘              │   │
│  │                                                                     │   │
│  │  Location: ~/.claude/skills/                                        │   │
│  │  Or: .claude/skills/ (project-specific)                             │   │
│  │                                                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        PLUGINS                                      │   │
│  │                                                                     │   │
│  │  Code extensions with tools and commands                            │   │
│  │                                                                     │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐              │   │
│  │  │ Built-in │  │ Bundled  │  │User Installed│  │Marketplace │              │   │
│  │  │ Plugins  │  │ Plugins  │  │ Plugins  │  │ Plugins  │              │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘              │   │
│  │                                                                     │   │
│  │  Location: ~/.claude/plugins/                                       │   │
│  │  Or: bundled in binary                                              │   │
│  │                                                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    MCP = PLUGINS v2                                   │   │
│  │                                                                     │   │
│  │  External servers providing tools                                   │   │
│  │  Declarative, language-agnostic                                      │   │
│  │                                                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
0000_start_here_index_and_recommended_reading_order.md
0100_project_overview_tech_stack_runtime_modes_and_folder_map.md
0200_startup_flow_entry_points_and_cold_start_sequence.md
0300_codebase_modules_layers_state_models_and_schemas.md
0400_system_architecture_and_design_rationale.md
0500_interactive_repl_request_flow_end_to_end.md
0600_headless_sdk_and_print_mode_request_flow_end_to_end.md
0700_mcp_integration_connection_and_tool_call_flow.md
0800_external_services_sdks_storage_and_local_dependencies.md
0900_environment_variables_settings_feature_flags_and_failure_modes.md
1000_non_obvious_patterns_gotchas_and_debugging_traps.md
1100_full_codebase_file_inventory_grouped_by_directory.md
kimi
00-overview.md
01-entrypoints.md
02-state-management.md
03-query-system.md
04-tools-system.md
05-tasks-system.md
06-ui-components.md
07-bridge-remote.md
08-services.md
09-skills-plugins.md
10-commands.md
11-testing-architecture.md
12-permission-system.md
13-build-system.md
14-ink-internals.md
15-git-internals.md
16-context-compaction.md
17-vim-mode.md
18-mailbox-notifications.md
19-session-persistence.md
20-hooks-system.md
21-error-recovery.md
README.md
qwen
00-overview.md
01-entry-points.md
02-query-engine.md
03-tools-and-tasks.md
04-commands-and-skills.md
05-state-management.md
06-ink-rendering.md
07-bridge-remote.md
08-mcp-services.md
09-services-overview.md
10-multi-agent.md
11-system-prompt-constants.md
12-tool-interface.md
13-memory-system.md
14-buddy-companion.md
15-keybindings.md
16-stop-hooks.md
17-vim-mode.md
18-upstreamproxy.md
19-cost-tracking-history.md
20-contexts-styles-onboarding.md
21-hooks.md
22-screens.md
tweets-explain
claude-code-memory-analysis.md
compact
memory-system
agentic-architecture

Skills

What is a Skill?

A skill is a reusable prompt template with optional parameter extraction.

TypeScript
// Skill structure
type Skill = {
  name: string                    // e.g., "commit"
  description: string             // What it does
  prompt: string                  // The prompt template
  parameters?: ParameterSchema[]  // Optional: extract from input
  tags?: string[]                  // For categorization
}
Skill File Format
Markdown
---
name: commit
description: Generate a conventional commit message
tags: [git, commit]
---

Analyze the changes and write a conventional commit message.

Changes:
{{diff}}

Follow the conventional commit format:
<type>(<scope>): <description>

[optional body]

[optional footer]
Parameter Extraction
Markdown
---
name: review-pr
description: Review a pull request
parameters:
  - name: pr_number
    type: number
    description: PR number to review
    extract: "PR #(\\d+)"
---

Review PR #{{pr_number}}:
1. Check code quality
2. Verify tests
3. Look for security issues

Input: "Please review PR #123" → Extracts: { pr_number: 123 }

Skills System Files

FilePurpose
skills/loadSkillsDir.tsLoad and parse skills
skills/bundledSkills.tsBuilt-in skills registry
skills/bundled/Bundled skill implementations
skills/mcpSkillBuilders.tsConvert MCP to skills
commands/skills/index.ts/skills command
Loading Skills
TypeScript
// skills/loadSkillsDir.ts
export async function loadSkillsFromDir(
  dirPath: string
): Promise<Skill[]> {
  const files = await glob('*.md', { cwd: dirPath })

  return Promise.all(
    files.map(async file => {
      const content = await readFile(join(dirPath, file), 'utf-8')
      return parseSkill(content)
    })
  )
}

function parseSkill(content: string): Skill {
  // Parse frontmatter + body
  const { attributes, body } = frontMatter(content)

  return {
    name: attributes.name,
    description: attributes.description,
    prompt: body,
    parameters: attributes.parameters,
    tags: attributes.tags,
  }
}
Skill Execution
TypeScript
// Skills become commands
const skillCommand: Command = {
  type: 'prompt',
  name: skill.name,
  description: skill.description,

  async getPromptForCommand(args: string[], context: CommandContext) {
    // Extract parameters from args
    const params = extractParameters(skill, args)

    // Substitute into prompt template
    const prompt = substituteTemplate(skill.prompt, params)

    // Return as user message
    return {
      messages: [{
        type: 'user',
        content: prompt,
      }],
    }
  },
}

Plugins

What is a Plugin?

A plugin is a code package that extends Claude Code with:

  • Custom tools
  • Custom commands
  • Custom UI components
  • Event hooks
Plugin Structure
Plain text
my-plugin/
├── claude-plugin.json    # Plugin manifest
├── index.js              # Entry point
├── tools/
│   └── MyTool.js         # Custom tools
├── commands/
│   └── mycommand.js      # Custom commands
└── hooks/
    └── onInit.js         # Lifecycle hooks
Plugin Manifest
JSON
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Does cool things",
  "entry": "index.js",
  "permissions": ["filesystem", "network"],
  "mcpServers": [{
    "name": "my-mcp-server",
    "command": "node",
    "args": ["./mcp-server.js"]
  }],
  "commands": [{
    "name": "mycommand",
    "description": "Run my command"
  }]
}

Plugin System Files

FilePurpose
utils/plugins/pluginLoader.tsLoad plugins from disk
utils/plugins/installedPluginsManager.tsManage installed plugins
utils/plugins/builtinPlugins.tsBuilt-in plugin registry
services/plugins/Plugin marketplace integration
plugins/bundled/Bundled plugin implementations
Plugin Loading
TypeScript
// utils/plugins/pluginLoader.ts
export async function loadPlugin(
  pluginPath: string
): Promise<LoadedPlugin> {
  // 1. Read manifest
  const manifest = await readManifest(join(pluginPath, 'claude-plugin.json'))

  // 2. Validate
  validateManifest(manifest)

  // 3. Load code
  const entryPath = join(pluginPath, manifest.entry)
  const pluginModule = await import(entryPath)

  // 4. Initialize
  const context = createPluginContext(manifest.permissions)
  await pluginModule.activate?.(context)

  return {
    manifest,
    module: pluginModule,
    tools: pluginModule.tools ?? [],
    commands: pluginModule.commands ?? [],
    context,
  }
}
Plugin Context
TypeScript
// What plugins can access
type PluginContext = {
  // Tools
  registerTool(tool: Tool): void
  unregisterTool(name: string): void

  // Commands
  registerCommand(command: Command): void
  unregisterCommand(name: string): void

  // Hooks
  onInit(callback: () => void): void
  onMessage(callback: (message: Message) => void): void
  onToolUse(callback: (toolUse: ToolUseBlock) => void): void

  // Storage (isolated per plugin)
  storage: PluginStorage

  // Logging
  log(message: string): void
}

Built-in vs Bundled vs External

Built-in Plugins
TypeScript
// plugins/builtinPlugins.ts
export const BUILTIN_PLUGINS = {
  'nextjs': {
    name: 'nextjs',
    description: 'Next.js best practices',
    skills: [nextJsSkill],
    isBuiltIn: true,
  },
  'vercel-react': {
    name: 'vercel-react',
    description: 'React performance tips',
    skills: [vercelReactSkill],
    isBuiltIn: true,
  },
}

Bundled with the binary, always available.

User-Installed Plugins
Bash
# Install from marketplace
$ claude plugin install @anthropic/git

# Install from local path
$ claude plugin install ./my-plugin

# Install from git
$ claude plugin install github.com/user/plugin

Stored in ~/.claude/plugins/.

Marketplace Plugins
TypeScript
// services/plugins/marketplace.ts
export async function searchMarketplace(
  query: string
): Promise<MarketplacePlugin[]> {
  const response = await fetch(
    `${MARKETPLACE_URL}/api/search?q=${encodeURIComponent(query)}`
  )
  return response.json()
}

MCP vs Plugins

Migration Path
Plain text
┌─────────────────────────────────────────────────────────────────┐
│              MCP IS THE FUTURE                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Old: Claude Code Plugin                    │
│  ─────────────────────────                  │
│  - JavaScript/TypeScript only               │
│  - Deep integration                         │
│  - Can access internal APIs                 │
│  - Harder to write                          │
│  - Security concerns                        │
│                                                                 │
│  New: MCP Server                            │
│  ─────────────                              │
│  - Any language                             │
│  - Standard protocol                        │
│  - Sandboxed (stdio/sse)                  │
│  - Easier to write                          │
│  - Better security                          │
│                                                                 │
│  Claude Code is moving toward MCP as the   │
│  primary extension mechanism.              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
Using MCP in Skills
TypeScript
// skills/mcpSkillBuilders.ts
export function mcpToolsToSkills(
  mcpTools: McpTool[],
  serverName: string
): Skill[] {
  return mcpTools.map(tool => ({
    name: `${serverName}_${tool.name}`,
    description: tool.description,
    prompt: `Use ${tool.name} with input: {{input}}`,
    // Tool is wrapped as a skill
    isMcpTool: true,
    mcpServer: serverName,
  }))
}

Skill Discovery

Auto-Discovery
TypeScript
// Automatically find skills in common locations
export async function discoverSkills(
  cwd: string
): Promise<Skill[]> {
  const locations = [
    // Global
    '~/.claude/skills/',

    // Project-specific
    `${cwd}/.claude/skills/`,
    `${cwd}/CLAUDE.md`,  // Single file skill

    // Git repo
    `${cwd}/.github/claude/skills/`,
  ]

  const allSkills: Skill[] = []
  for (const location of locations) {
    if (await fileExists(location)) {
      const skills = await loadSkillsFromDir(location)
      allSkills.push(...skills)
    }
  }

  return allSkills
}
CLAUDE.md Files

Special file that defines project context:

Markdown
# MyProject Context

This is a Next.js 14 app with:
- App Router
- Prisma ORM
- Tailwind CSS

## Common Tasks

### Database Migration
Run migrations with: `npx prisma migrate dev`

### Testing
Run tests with: `npm test`

Loaded automatically as context.

Plugin Lifecycle

Plain text
┌─────────────────────────────────────────────────────────────────┐
│                    PLUGIN LIFECYCLE                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  INSTALL                                                        │
│     │                                                           │
│     ▼                                                           │
│  ┌─────────────┐                                               │
│  │  Download   │  Fetch from registry/marketplace              │
│  │  Package    │                                               │
│  └──────┬──────┘                                               │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐                                               │
│  │  Validate   │  Check manifest, permissions                    │
│  │  Manifest   │                                               │
│  └──────┬──────┘                                               │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐                                               │
│  │   Load      │  Require() entry point                       │
│  │   Code      │                                               │
│  └──────┬──────┘                                               │
│         │                                                       │
│  LOAD (per session)                                            │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐                                               │
│  │  Activate   │  Call plugin.activate(context)                │
│  │  Plugin     │                                               │
│  └──────┬──────┘                                               │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐                                               │
│  │  Register   │  Tools, commands, hooks added                 │
│  │  Components │                                               │
│  └──────┬──────┘                                               │
│         │                                                       │
│  RUNTIME ──► Hooks fire on events                             │
│         │                                                       │
│  UNLOAD (session end)                                          │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐                                               │
│  │  Deactivate │  Call plugin.deactivate()                      │
│  │  Plugin     │  Cleanup                                      │
│  └──────┬──────┘                                               │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────┐                                               │
│  │  Unregister │  Remove tools, commands                       │
│  │  Components │                                               │
│  └─────────────┘                                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Best Practices

Skill Writing
Markdown
---
name: good-skill
---

<!-- GOOD: Specific, actionable, parameterized -->

Review this code for:
1. Type safety issues
2. Performance problems
3. Security vulnerabilities

Code:
```{{language}}
{{code}}

Check this code.

Plain text

### Plugin Security

```typescript
// Validate all inputs
function safeTool(input: unknown): Result {
  const parsed = schema.safeParse(input)
  if (!parsed.success) {
    return { error: 'Invalid input' }
  }

  // Escape shell commands
  const safePath = escapePath(parsed.data.path)

  // Check permissions
  if (!isPathAllowed(safePath)) {
    return { error: 'Path not allowed' }
  }

  return execute(safePath)
}

Key Concepts

1. Skills = Declarative

Markdown + frontmatter. Easy to write, version control, share.

2. Plugins = Imperative

JavaScript/TypeScript code. Powerful, but more complex.

3. MCP = Standard

Protocol-based. Language-agnostic, sandboxed, future-proof.

4. Discovery is Automatic

Skills found in standard locations. No registration needed.

5. Permissions Matter

Plugins declare permissions. Users review before install.

Related Documentation

  • Tools System - How plugin tools work
  • Commands - How plugin commands work
  • Services - MCP services