Plugin System

Plugins extend AFK with skills, agents, slash commands, and MCP servers. They are distributed as directories and can be installed globally or per-project.

Plugin scan paths

AFK scans these locations (highest to lowest priority):

1. <projectDir>/.afk/plugins/ — project-level plugins
2. ~/.afk/plugins/ — user-level plugins

Each subdirectory is treated as a candidate plugin if it contains a plugin manifest.

Plugin manifest

The preferred manifest location is .afk-plugin/plugin.json at the plugin root. AFK also accepts .claude-plugin/plugin.json and root-level plugin.json as deprecated compatibility fallbacks.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does",
  "author": "your-org",
  "dependencies": ["shared-quality-tools"]
}

Plugin structure

my-plugin/
├── .afk-plugin/
│   └── plugin.json        # manifest
├── skills/
│   └── deploy-helper/
│       └── SKILL.md       # contributes skill "my-plugin:deploy-helper"
├── agents/
│   └── reviewer.md        # contributes agent "my-plugin:reviewer"
├── commands/
│   └── check-deps.md      # contributes slash command "/my-plugin:check-deps"
├── .mcp.json              # contributes MCP servers
└── hooks.json             # contributes hooks

Contributing skills

Place SKILL.md files in skills/<name>/. Plugin skills are namespaced as pluginName:skillName and invoked as /pluginName:skillName.

# skills/deploy-helper/SKILL.md
---
name: deploy-helper
description: Use when deploying to production. Enforces pre-deploy checks.
---

Before deploying to production:
1. Verify all tests pass: `bun test`
2. Check the deployment checklist in docs/deploy-checklist.md
3. Confirm with the team in #deploys before merging
...

Skill scripts and assets can reference the plugin root via ${CLAUDE_PLUGIN_ROOT} — the path is injected into the skill body.

Contributing agents

Place agent definition .md files in the agents/ directory. Plugin agents are namespaced as pluginName:agentName.

# agents/reviewer.md
---
name: reviewer
description: Performs thorough code reviews. Use for PR reviews and architecture audits.
model: claude-sonnet
tools:
  - read_file
  - glob
  - grep
  - workspace_diff
---

You are a senior engineer performing a rigorous code review...

Contributing slash commands

Place command .md files in commands/. Commands are invoked as /pluginName:commandName in the browser chat.

# commands/check-deps.md
---
name: check-deps
description: Audit npm/bun dependencies for vulnerabilities and outdated packages.
---

Audit the project's dependencies:

1. Run `bun audit` and report any vulnerabilities.
2. Check for packages more than 2 major versions behind.
3. Flag any packages with known CVEs.

Contributing MCP servers

Add a .mcp.json file at the plugin root. MCP server names are namespaced as pluginName__serverName.

{
  "mcpServers": {
    "my-service": {
      "command": "${CLAUDE_PLUGIN_ROOT}/bin/mcp-server",
      "env": {
        "DATA_DIR": "${CLAUDE_PLUGIN_DATA}",
        "API_TOKEN": "${secrets.my_service_token}"
      }
    }
  }
}

Supported substitutions in .mcp.json:

• ${CLAUDE_PLUGIN_ROOT} — absolute path to the plugin directory
• ${CLAUDE_PLUGIN_DATA} — writable data directory for this plugin
• ${secrets.name}, Claude-compatible ${user_config.name}, and legacy ${env.name} — secret values stored in Account → Secrets

Contributing hooks

Add a hooks.json file at the plugin root. Uses the same format as settings hooks. Commands may use ${CLAUDE_PLUGIN_ROOT} substitution.

{
  "Notify": {
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/notify.sh",
    "blocking": false
  },
  "BeforeToolUse": {
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/policy.py",
    "blocking": true
  }
}

Installing plugins

Plugins can be installed manually, from the browser UI, or through configured marketplace sources. For marketplace source schema, dependency behavior, git-backed sync, and examples, see Plugin marketplace.

Manual install

# Install a plugin from a git repository
git clone https://github.com/example/afk-plugin ~/.afk/plugins/my-plugin

# Or copy a local directory
cp -r ./my-plugin ~/.afk/plugins/

Via the browser UI

The browser's Plugin manager (accessible from Account → Plugins or the /plugins command) supports installing, updating, and removing plugins. Filesystem and git operations run on the selected daemon. After installing or updating plugins, reload the session capabilities so new skills, agents, commands, MCP servers, and hooks are available.

Reloading plugins

After installing or modifying a plugin, call reload in the agent chat or use the /reload browser command. This rescans plugins, skills, commands, agents, MCP servers, hooks, and prompt-related config — without restarting the session.

Namespacing reference

Example: complete plugin

# Directory structure
~/.afk/plugins/security-scanner/
├── .afk-plugin/
│   └── plugin.json
├── skills/
│   └── security-audit/
│       ├── SKILL.md
│       └── scripts/
│           └── run-audit.sh
├── agents/
│   └── security-expert.md
└── hooks.json

# plugin.json
{
  "name": "security-scanner",
  "version": "1.0.0",
  "description": "Security auditing tools and agents for AFK",
  "author": "your-org"
}

# skills/security-audit/SKILL.md
---
name: security-audit
description: Use when auditing code for security vulnerabilities.
---
Run a comprehensive security audit: check dependencies, scan for secrets,
review auth flows, and check for OWASP Top 10 issues.

# hooks.json
{
  "BeforeToolUse": {
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-sensitive-paths.sh",
    "blocking": true
  }
}