Skip to main content

Plugins

Plugins provide a way to package and distribute multiple agent components as a single unit. Instead of managing individual skills, hooks, and configurations separately, plugins bundle everything together for easier installation and distribution.

What are plugins?​

A plugin is a directory structure that can contain:

  • Skills: Specialized knowledge and workflows
  • Hooks: Event handlers for tool lifecycle
  • MCP Config: External tool server configurations
  • Agents: Specialized agent definitions
  • Commands: Slash commands

Plugins vs skills​

Understanding the difference helps you choose the right approach:

Skills

Specialized prompts for specific tasks

  • One skill = one specific capability
  • Just a SKILL.md file (+ optional resources)
  • Lightweight and focused
  • Quick to create and share

When to use:

  • Adding single capabilities
  • Simple workflows
  • Domain-specific knowledge
  • Quick solutions
Plugins

Multi-component bundles

  • Multiple skills + hooks + config
  • Complete feature ecosystems
  • Coordinated components
  • Professional distribution

When to use:

  • Complete feature sets
  • Tool integrations
  • Team standards
  • Commercial distributions

Comparison table​

AspectSkillsPlugins
ComplexitySimpleComprehensive
ComponentsKnowledge onlySkills + hooks + MCP + commands
Use CaseSingle capabilityComplete feature set
CreationFew minutesPlanned development
DistributionCopy directoryStructured package
MaintenanceIndividual filesCoordinated bundle

When to use each​

Use a Skill when you need:

  • A single reusable prompt or workflow
  • Domain-specific knowledge
  • Simple automation
  • Quick solutions

Use a Plugin when you need:

  • Multiple related skills working together
  • Event handlers (hooks) for tool actions
  • External tool integrations (MCP)
  • Complete platform integrations
  • Team or organizational standards

Example: Code Quality

As separate skills:

.agents/skills/
├── python-linting/
├── code-review/
└── pre-commit-setup/

As a plugin:

code-quality-plugin/
├── .plugin/plugin.json          # or .claude-plugin/plugin.json
├── skills/
│   ├── linting/
│   ├── review/
│   └── setup/
├── hooks/hooks.json             # Post-edit linting
└── .mcp.json                    # Code analysis tools

The plugin version bundles all quality-related capabilities and automatically runs checks after file edits.

Plugin structure​

A complete plugin follows this directory structure:

plugin-name/
├── .plugin/                     # or .claude-plugin/
│   └── plugin.json              # Required: Plugin metadata
├── skills/
│   └── skill-name/
│       └── SKILL.md             # Individual skills
├── hooks/
│   └── hooks.json               # Tool lifecycle hooks
├── agents/
│   └── agent-name.md            # Specialized agents
├── commands/
│   └── command-name.md          # Slash commands
├── .mcp.json                    # MCP server config
└── README.md                    # Documentation

Required components​

Only one file is required:

  • plugin-name/.plugin/plugin.json or plugin-name/.claude-plugin/plugin.json: Plugin metadata

All other components are optional—include only what your plugin needs.

Plugin metadata​

The plugin.json file defines your plugin:

{
  "name": "code-quality",
  "version": "1.0.0",
  "description": "Code quality tools and workflows",
  "author": {
    "name": "Your Name",
    "email": "your@email.com"
  },
  "license": "MIT",
  "repository": "https://github.com/example/code-quality-plugin"
}

The author field can also be a simple string such as "Your Name".

Plugin components explained​

Skills

Skills in plugins work identically to standalone skills. Each skill has its own directory with a SKILL.md file:

skills/
├── linting/
│   ├── SKILL.md
│   └── scripts/
└── testing/
    └── SKILL.md

See Skills Documentation for skill creation details.

Hooks

Hooks are event handlers that run during tool lifecycle events:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "file_editor",
        "hooks": [
          {
            "type": "command",
            "command": "ruff check $FAHEEMCODE_PROJECT_DIR",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Hook commands have access to these environment variables:

  • $FAHEEMCODE_PROJECT_DIR: Path to the project directory
  • $FAHEEMCODE_SESSION_ID: Current session identifier
  • $FAHEEMCODE_EVENT_TYPE: The triggering event type
  • $FAHEEMCODE_TOOL_NAME: Name of the tool that triggered the hook

Common use cases:

  • Run linters after file edits
  • Validate tool inputs
  • Log tool usage
  • Trigger dependent actions

Available hook events:

  • PreToolUse: Before tool execution
  • PostToolUse: After tool execution
  • UserPromptSubmit: When the user submits a prompt
  • SessionStart: When the session starts
  • SessionEnd: When the session ends
  • Stop: When execution stops
MCP configuration

MCP (Model Context Protocol) servers provide external tools and resources:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "github": {
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Use cases:

  • Connect to external APIs
  • Add specialized tools
  • Integrate third-party services

Learn more: Model Context Protocol

Agents

Specialized agent definitions for specific tasks:

---
name: code-reviewer
description: Specialized agent for code review tasks
---

# Code Review Agent

This agent specializes in reviewing code according to team standards...

Agents in plugins can use the plugin's skills and hooks automatically.

Commands

Custom slash commands for plugin functionality:

---
name: /lint
description: Run linters on current file
---

# Lint Command

Run configured linters on the current file...

Commands provide quick access to plugin features.

Using plugins​

How you use plugins depends on your platform:

Via configuration file:

Create ~/.faheem-code/config.toml:

[plugins]
sources = [
  "/path/to/local/plugin",
  "github:org/plugin-repo",
]

Via command line:

faheemcode --plugin /path/to/plugin
faheemcode --plugin github:org/plugin-repo

Plugins are loaded when Faheem Code starts.

Installing plugins​

From a local directory​

  1. Verify plugin structure:

    ls plugin-dir/.plugin/plugin.json || ls plugin-dir/.claude-plugin/plugin.json

  2. Use the plugin path in your configuration or command line

From GitHub​

Plugins can be loaded directly from GitHub repositories:

github:SMART-National-Solution/faheem-code-example-plugin
github:org/repo/path/to/plugin    # For monorepos
github:org/repo#branch-name        # Specific branch
github:org/repo#v1.0.0            # Specific tag

Plugin sources​

Official registry

github.com/SMART-National-Solution/faheem-code-extensions

Community-maintained plugins

Custom repositories

Your own GitHub repositories

Organization or private plugins

Creating plugins​

To create your own plugin:

1. Plan your components​

Determine what your plugin needs:

  • Which skills?
  • What hooks for automation?
  • Any MCP integrations?
  • Custom commands?

2. Create directory structure​

mkdir -p my-plugin/.plugin
mkdir -p my-plugin/skills
mkdir -p my-plugin/hooks

Use .claude-plugin/ instead of .plugin/ if you want Claude Code-compatible naming.

3. Create plugin metadata​

Create my-plugin/.plugin/plugin.json (or my-plugin/.claude-plugin/plugin.json):

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My custom plugin",
  "author": {
    "name": "Your Name"
  }
}

4. Add components​

Add skills, hooks, and other components as needed:

my-plugin/
├── .plugin/plugin.json          # or .claude-plugin/plugin.json
├── skills/
│   └── my-skill/
│       └── SKILL.md
└── hooks/
    └── hooks.json

5. Test locally​

Load your plugin and verify all components work:

faheemcode --plugin /path/to/my-plugin

6. Distribute​

Options for distribution:

  • GitHub repository: Push to GitHub and share URL
  • File sharing: Zip and share directory
  • Package registry: Submit to official registry

Plugin examples​

Code quality plugin

Contains:

  • Python linting skill
  • JavaScript linting skill
  • Post-edit hooks for auto-linting
  • Pre-commit setup

Use case: Enforce code standards

DevOps plugin

Contains:

  • Kubernetes deployment skill
  • Docker build skill
  • CI/CD workflow skill
  • kubectl MCP server

Use case: Infrastructure management

API integration plugin

Contains:

  • REST API client skill
  • Authentication skill
  • Rate limiting hooks
  • API MCP server

Use case: External service integration

Testing plugin

Contains:

  • Unit testing skill
  • Integration testing skill
  • Post-code hooks for test runs
  • Coverage commands

Use case: Automated testing

Plugin development best practices​

Start with skills

Begin by creating the core skills your plugin needs. Test them individually before bundling.

Add automation with hooks

Identify repetitive tasks and automate them with hooks. Example: run linters after file edits.

Integrate external tools

Add MCP servers for external tool integration. This provides your skills with additional capabilities.

Document thoroughly

Include a comprehensive README explaining:

  • What the plugin does
  • How to install it
  • Configuration options
  • Example usage
Version carefully

Use semantic versioning (major.minor.patch) and document breaking changes.

Troubleshooting​

Plugin not loading

Check:

  • .plugin/plugin.json or .claude-plugin/plugin.json exists and is valid JSON
  • Plugin path is correct
  • All referenced files exist

Debug:

# Verify structure
ls -la plugin-name/.plugin/plugin.json || ls -la plugin-name/.claude-plugin/plugin.json

# Check JSON syntax
(cat plugin-name/.plugin/plugin.json 2>/dev/null || cat plugin-name/.claude-plugin/plugin.json) | python -m json.tool
Skills not triggering

Check:

  • Skills have valid SKILL.md files
  • Frontmatter includes triggers
  • Trigger keywords match your prompts

Test: Use explicit trigger keywords from the skill's frontmatter.

Hooks not running

Check:

  • hooks/hooks.json syntax is valid
  • Hook matchers target the right tools
  • Commands are executable

Debug: Check logs for hook execution errors.

Next steps​

Further reading​

For SDK developers: