docs: sync KB — claude-plugins-marketplace, permission-manager-classifier-development
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 5s
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 5s
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
fa11cd0431
commit
b192b3ca47
130
development/claude-plugins-marketplace.md
Normal file
130
development/claude-plugins-marketplace.md
Normal file
@ -0,0 +1,130 @@
|
||||
---
|
||||
title: "Claude Plugins Personal Marketplace"
|
||||
description: "Reference for the cal/claude-plugins Gitea repo — personal Claude Code plugin marketplace with 20 plugins (10 agents, 10 skills), including installation, adding new plugins, and maintenance."
|
||||
type: reference
|
||||
domain: development
|
||||
tags: [claude-code, plugins, gitea, marketplace]
|
||||
---
|
||||
|
||||
# Claude Plugins Personal Marketplace
|
||||
|
||||
**Repo:** `cal/claude-plugins` on Gitea ([https://git.manticorum.com/cal/claude-plugins](https://git.manticorum.com/cal/claude-plugins))
|
||||
**Local clone:** `/mnt/NV2/Development/claude-plugins/`
|
||||
**License:** AGPL-3.0
|
||||
|
||||
## What It Is
|
||||
|
||||
A self-hosted Claude Code plugin marketplace containing 20 plugins (10 agents, 10 skills) extracted from local `~/.claude/` definitions. Registered via `claude plugin marketplace add https://git.manticorum.com/cal/claude-plugins.git` (stored in `~/.claude/settings.json` under `extraKnownMarketplaces`).
|
||||
|
||||
## Plugin Inventory
|
||||
|
||||
### Agents (10)
|
||||
|
||||
| Name | Description |
|
||||
|------|-------------|
|
||||
| architect | PRD creation, system design, technical specs |
|
||||
| claude-researcher | Web research with multi-query decomposition |
|
||||
| designer | UX/UI design review, visual design, accessibility |
|
||||
| engineer | Code implementation, debugging, optimization, testing |
|
||||
| issue-worker | Autonomous Gitea issue fixer — creates PRs |
|
||||
| pentester | Penetration testing and vulnerability assessments |
|
||||
| pr-reviewer | Automated Gitea PR reviewer |
|
||||
| swarm-coder | Implementation agent for orchestrated swarms |
|
||||
| swarm-reviewer | Code reviewer for orchestrated swarms |
|
||||
| swarm-validator | Spec validator for orchestrated swarms |
|
||||
|
||||
### Skills (10)
|
||||
|
||||
| Name | Description |
|
||||
|------|-------------|
|
||||
| backlog | Surface next Gitea issue or TODO to work on |
|
||||
| create-scheduled-task | Manage headless Claude scheduled tasks on systemd timers |
|
||||
| json-pretty | JSON prettifier CLI tool |
|
||||
| optimise-claude | Guide for writing effective CLAUDE.md files |
|
||||
| playwright-cli | Browser automation for testing and screenshots |
|
||||
| project-plan | Generate PROJECT_PLAN.json for task tracking |
|
||||
| resume-tailoring | Tailored resume generation with company research |
|
||||
| save-doc | Save documentation to KB with proper frontmatter |
|
||||
| youtube-transcriber | Transcribe YouTube videos via OpenAI GPT-4o-transcribe |
|
||||
| z-image | Local GPU image generation with Z-Image Turbo |
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Marketplace is already registered. To install a plugin:
|
||||
claude plugin install <name>@cal-claude-plugins --scope user
|
||||
|
||||
# Enable/disable:
|
||||
claude plugin enable <name>@cal-claude-plugins
|
||||
claude plugin disable <name>@cal-claude-plugins
|
||||
|
||||
# Update marketplace cache (pulls latest from Gitea):
|
||||
claude plugin marketplace update cal-claude-plugins
|
||||
```
|
||||
|
||||
## Adding a New Plugin
|
||||
|
||||
### Directory Structure
|
||||
|
||||
Each plugin lives under `plugins/<name>/` with this layout:
|
||||
|
||||
```
|
||||
plugins/<name>/
|
||||
.claude-plugin/
|
||||
plugin.json # name, description, version
|
||||
skills/<name>/ # for skill plugins
|
||||
SKILL.md # skill definition with frontmatter
|
||||
agents/ # for agent plugins
|
||||
<name>.md # agent definition
|
||||
```
|
||||
|
||||
### plugin.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "One-line description of what it does.",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
### SKILL.md Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
allowed-tools: Read,Write,Edit,Glob,Grep,Bash
|
||||
description: What this skill does
|
||||
user-invocable: true
|
||||
---
|
||||
```
|
||||
|
||||
### Register in marketplace.json
|
||||
|
||||
Add an entry to `.claude-plugin/marketplace.json` in the `plugins` array:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"source": "./plugins/my-plugin",
|
||||
"description": "One-line description."
|
||||
}
|
||||
```
|
||||
|
||||
### Commit and Push
|
||||
|
||||
```bash
|
||||
cd /mnt/NV2/Development/claude-plugins
|
||||
git add plugins/my-plugin .claude-plugin/marketplace.json
|
||||
git commit -m "feat: add my-plugin skill"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
Then update the cache: `claude plugin marketplace update cal-claude-plugins`
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **SKILL.md `name:` must match directory name** — a mismatch causes the skill to not load (e.g., the `optimise-claude` plugin had `name: claude-optimised` which broke it)
|
||||
- **SSH remote** — uses `git@git.manticorum.com:cal/claude-plugins.git` via SSH config alias (`~/.ssh/config` maps `git.manticorum.com` → `10.10.0.225` as user `git`)
|
||||
- **No secrets** — repo is public; plugins are just prompt definitions, no credentials
|
||||
- **Plugins requiring MCP servers** — `backlog`, `issue-worker`, and `pr-reviewer` require `gitea-mcp`; they install fine without it but those tool calls won't execute
|
||||
- **sync-kb does NOT apply here** — this is a standalone repo, not part of claude-home. Changes require manual commit/push
|
||||
138
development/permission-manager-classifier-development.md
Normal file
138
development/permission-manager-classifier-development.md
Normal file
@ -0,0 +1,138 @@
|
||||
---
|
||||
title: "Writing Classifiers for permission-manager (agent-toolkit)"
|
||||
description: "Guide to adding new command classifiers to the St0nefish/agent-toolkit permission-manager plugin for Claude Code, covering project structure, conventions, testing, and PR workflow."
|
||||
type: guide
|
||||
domain: development
|
||||
tags: [claude-code, permissions, agent-toolkit, bash, classifier]
|
||||
---
|
||||
|
||||
# Writing Classifiers for permission-manager
|
||||
|
||||
## Overview
|
||||
|
||||
The `permission-manager@agent-toolkit` plugin (St0nefish/agent-toolkit) provides a `cmd-gate` PreToolUse hook that classifies Bash commands before execution. Classifiers are bash scripts in `plugins-claude/permission-manager/scripts/classifiers/` that decide whether commands should be auto-allowed, require user approval, or be denied.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
plugins-claude/permission-manager/
|
||||
scripts/
|
||||
cmd-gate.sh # Hook entry point
|
||||
lib-classify.sh # Classification framework + dispatcher
|
||||
classifiers/
|
||||
cargo.sh # cargo/rust
|
||||
docker.sh # docker/compose
|
||||
find.sh # find (deny -delete/-exec rm)
|
||||
git.sh # git (with protected branch logic)
|
||||
gh.sh # GitHub CLI
|
||||
gradle.sh # gradle/gradlew
|
||||
jvm-tools.sh # java/mvn
|
||||
npm.sh # npm/node/pnpm/yarn/npx
|
||||
pip.sh # pip/python/poetry/pyenv
|
||||
read-only-tools.sh # cat, ls, grep, jq, ps, etc.
|
||||
tea.sh # Gitea CLI
|
||||
uv.sh # uv/uvx (added 2026-03-18)
|
||||
tests/permission-manager/
|
||||
test-classify.sh # Main test harness (618+ tests)
|
||||
```
|
||||
|
||||
## Classification Decisions
|
||||
|
||||
Three possible outcomes:
|
||||
- **`allow`** — auto-approve, no prompt (read-only or safe local operations)
|
||||
- **`ask`** — prompt user for approval (destructive, remote, or elevated operations)
|
||||
- **`deny`** — block the command (e.g., `find -delete`)
|
||||
- **passthrough** — `return 0` without calling allow/ask/deny; defers to Claude Code's built-in permission system
|
||||
|
||||
## Classifier Conventions
|
||||
|
||||
### File Header
|
||||
```bash
|
||||
# shellcheck shell=bash
|
||||
# shellcheck source=../lib-classify.sh
|
||||
```
|
||||
|
||||
### Function Naming
|
||||
- Entry point: `check_<tool>()` (e.g., `check_uv`, `check_docker`)
|
||||
- Subcommand extractor: `extract_<tool>_subcommand()` (for tools with global flags)
|
||||
|
||||
### Entry Guard Pattern
|
||||
|
||||
Simple tools (cargo, npm, pip) use `awk` + `case`:
|
||||
```bash
|
||||
local first_token
|
||||
first_token=$(echo "$command" | awk '{print $1}')
|
||||
case "$first_token" in
|
||||
uv) ;;
|
||||
*) return 0 ;;
|
||||
esac
|
||||
```
|
||||
|
||||
Complex tools (docker, git) use `perl` guard:
|
||||
```bash
|
||||
echo "$command" | perl -ne '$f=1,last if /^\s*docker(\s|$)/; END{exit !$f}' || return 0
|
||||
```
|
||||
|
||||
### Reason Message Style
|
||||
- Read-only: `"<tool> <subcmd> is read-only"`
|
||||
- Local ops: `"<tool> <subcmd> is a local build/dev operation"`
|
||||
- Ask: `"<tool> <subcmd> modifies <what>"`
|
||||
- Deny: `"<tool> <subcmd> is not allowed"`
|
||||
|
||||
### Classification Philosophy (from existing classifiers)
|
||||
| Category | Decision | Examples |
|
||||
|----------|----------|---------|
|
||||
| Read-only inspection | allow | `git status`, `docker ps`, `pip list` |
|
||||
| Local build/install | allow | `npm install`, `pip install`, `cargo build` |
|
||||
| Global tool install | ask | `cargo install`, `uv tool install` |
|
||||
| Package uninstall | ask | `pip uninstall`, `uv pip uninstall` |
|
||||
| Publish/deploy | ask | `npm publish`, `cargo publish`, `uv publish` |
|
||||
| Execute arbitrary packages | passthrough | `npx`, `uvx`, `uv run --with` |
|
||||
| Destructive operations | deny | `find -delete` |
|
||||
|
||||
## Wiring a New Classifier
|
||||
|
||||
In `lib-classify.sh`, add to `classify_single_command()`:
|
||||
```bash
|
||||
check_<tool>
|
||||
[[ "$CLASSIFY_MATCHED" -eq 1 ]] && return 0
|
||||
```
|
||||
|
||||
Place it logically near related classifiers (e.g., `check_uv` after `check_pip`).
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Format
|
||||
```bash
|
||||
run_test_both <expected> "<command>" ["label"]
|
||||
```
|
||||
`run_test_both` runs the test in both Claude and Copilot modes. Expected values: `allow`, `ask`, `deny`, `none` (passthrough).
|
||||
|
||||
### Test Section Structure
|
||||
```bash
|
||||
# ===== ALLOW: <tool> read-only =====
|
||||
echo "── <tool> read-only ──"
|
||||
run_test_both allow "<command>"
|
||||
|
||||
# ===== ALLOW: <tool> local build/dev =====
|
||||
echo "── <tool> local build/dev ──"
|
||||
...
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
bash tests/permission-manager/test-classify.sh # Full suite
|
||||
bash tests/permission-manager/test-classify.sh uv # Filter by keyword
|
||||
```
|
||||
|
||||
## PR Workflow
|
||||
|
||||
1. Fork `St0nefish/agent-toolkit` on GitHub
|
||||
2. Branch from `master` (not `main`)
|
||||
3. Add classifier, wire it, update tests
|
||||
4. Run full test suite — zero regressions required
|
||||
5. PR via `gh pr create --repo St0nefish/agent-toolkit --base master`
|
||||
|
||||
## Reference PR
|
||||
|
||||
- [PR #38: feat: add uv/uvx classifier](https://github.com/St0nefish/agent-toolkit/pull/38) — full uv/uvx classifier with 102 tests, submitted 2026-03-18
|
||||
Loading…
Reference in New Issue
Block a user