agentleFS
eehricheehrich/ScarabHive/.claude/skills/hive/SKILL.md

hive

Skill2 starsChanged 10 days agoApache-2.0View on GitHub

Python & YAML coding agent for the AgentSystem core, plugins, config, and architecture

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 7 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Plugin-based architecture: every plugin is a tool server (agent_system/tools/)

    line 100
  2. Very specific:

    Read docs: Start with docs/_arch_*.md for architecture, then specific design docs

    line 129
  3. Very specific:

    Plan: Use todo tool for multi-step tasks

    line 131
  4. Distinctive:

    Test (lint): Run Ruff and Mypy (commands below)

    line 134
  5. Distinctive:

    Test (API): Run API task, test endpoints

    line 136
  6. Distinctive:

    Document: Update relevant docs if behavior changes

    line 137
  7. Distinctive:

    Tests-first: Run pytest after EVERY change, fix failures immediately

    line 180
  8. Distinctive:

    Type safety: Use Pydantic models, run Mypy

    line 181
  9. Distinctive:

    Lint clean: Run Ruff before committing

    line 182
  10. Very specific:

    Schema sync: Update JSON schemas in schemas/ when config models change

    line 183
  11. Distinctive:

    No test-only production code: Keep tests separate from implementation

    line 184

“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

AgentSystem Coding Agent

Senior Python/YAML architect for the AgentSystem Core Framework – a modular, extensible AI agent framework.

Name of the System is ScarabHive

Quick Reference

ResourcePath
Core Systemsrc/agent_system/
Pluginssrc/plugins/
Plugin Teststests/plugins/
Core Teststests/ (agent/, app/, config/, llm/, tools/, etc.)
Agent Configsconfig/agents/
System Configconfig/ (config.yaml, llm.yaml, plugins.yaml, mcp_servers.yaml)
Documentationdocs/
Architecture Docsdocs/_arch_*.md
Design Docsdocs/*_design.md
Virtual Env.venv/
Schemasschemas/

Architecture Overview

Core Components (src/agent_system/)

ComponentPurpose
core/Agent runtime, session management, tool execution
llm/LLM provider abstraction (OpenAI, Anthropic, Google, etc.)
tools/Tool servers: the plugin base class, the registry, the status bus
plugins/Plugin registry, discovery, loading
config/Configuration models and merging
api/FastAPI REST endpoints
services/Business logic services
hooks/Hook system for lifecycle events
auth/Authentication & user management
cli_utils/CLI helpers; agent-cli's parser (cli_parser.py) and commands (commands/)
servers/Server implementations
utils/Shared utilities
app.pyFastAPI application factory
agent_cli.pyCLI entry point (parse, load config, dispatch)
agent_run.pyAgent run execution logic

Plugin Categories (src/plugins/)

Over 60 general-purpose plugins. Key plugins:

PluginPurpose
basic_agent/Core agent orchestration
basic_operations/Basic tool operations
cognitive_stack/Multi-step reasoning
sequential_thinking/Step-by-step reasoning
context_engineer/Context engineering
context_summarizer/Conversation summarization
context_usage_tracker/Context usage tracking
sub_agent_manager/Sub-agent spawning & control
agent_continuation/Agent session continuation
task_switch/Task context switching
llm_router/Multi-LLM routing
memory/Persistent memory storage
file_ops/File system operations
terminal/Shell command execution
ssh_control/SSH remote control
script_interpreter/Script execution
sqlite_query/SQLite database queries
todo/Task management
http_server/HTTP server utilities
audio_ops/Audio file operations
duckduckgo_search/DuckDuckGo web search
tavily_search/Tavily web search
twitter_search/Twitter/X search
web_scraper/Web content extraction
research/Web research agent (config only: agent + skill)
forge/GitLab/GitHub for the coder: issues, merge/pull requests, CI, push, merge
weather/Weather information
debate_forum/Multi-agent debate coordination
comfyui/ComfyUI image generation
message_debugger/LLM request/response debugging
message_validator/Message validation
request_logger/Logs each LLM call and run end (hooks)
log_viewer/Log viewing & filtering
batch_monitor/Batch operation monitoring
user_management/User management
lessons_learned/Lessons learned storage
datetime/Date/time utilities
simple_prompt_inject/Prompt injection utility

Further plugin roots (src/plugins_<name>/, loaded through plugins.plugin_dirs: src/plugins*) may hold plugins outside the open-source release; they bring their own docs and are not covered here.

Key Design Patterns

  • Plugin-based architecture: every plugin is a tool server (agent_system/tools/)
  • Configuration-driven agents: YAML-defined agents in config/agents/
  • Hook system: Lifecycle interception (docs/plugin_hooks.md)
  • Session management: Multi-user, persistent sessions
  • Streaming: SSE for real-time status updates
  • Cancellation: Token-based operation cancellation

Key Documentation

Building or changing a plugin, tool, hook, agent YAML or sub-agent: load the plugin-authoring skill first. It is verified against the code; the plugin docs below are partly stale.

DocumentPurpose
_arch_agent_system_architecture.mdCore system architecture
_arch_plugin_architecture.mdPlugin system design
_arch_app_architecture.mdFastAPI app structure
_arch_cli_architecture.mdCLI architecture
plugin_authoring.mdHow to write plugins
plugin_hooks.mdHook system guide
config_based_agents.mdYAML agent definition
session_management.mdSession lifecycle
mcp_configuration.mdExternal MCP server setup
tool_execution.mdTool invocation flow

Workflow

  1. Understand the task requirements
  2. Read docs: Start with docs/_arch_*.md for architecture, then specific design docs
  3. Read code: Relevant module in src/agent_system/ or src/plugins/
  4. Plan: Use todo tool for multi-step tasks
  5. Implement: Edit code, update config schemas if needed
  6. Test (unit): pytest tests/<module>/test_*.py -v
  7. Test (lint): Run Ruff and Mypy (commands below)
  8. Test (CLI): .venv/Scripts/agent-cli.exe --help
  9. Test (API): Run API task, test endpoints
  10. Document: Update relevant docs if behavior changes

Commands

# Activate venv (Windows Git Bash)
source .venv/Scripts/activate

# Run specific tests
.venv/Scripts/python.exe -m pytest tests/plugins/test_plugin_memory.py -v
.venv/Scripts/python.exe -m pytest tests/agent/ -v
.venv/Scripts/python.exe -m pytest tests/config/ -v

# Run all tests (use sparingly, prefer targeted tests)
.venv/Scripts/python.exe -m pytest -q

# Linting & type checking
.venv/Scripts/python.exe -m ruff check src --fix
.venv/Scripts/python.exe -m mypy src --show-traceback

# CLI
.venv/Scripts/agent-cli.exe --help
.venv/Scripts/agent-cli.exe chat --agent basic_agent
.venv/Scripts/agent-cli.exe plugins

# API server
.venv/Scripts/agent-api.exe

Configuration Files

FilePurpose
config/config.yamlMain system config (auth, logging, paths)
config/llm.yamlLLM provider settings
config/plugins.yamlPlugin enable/disable, settings
config/mcp_servers.yamlExternal MCP server connections
config/agents/*.yamlAgent definitions
pyproject.tomlProject dependencies, build config
pytest.iniTest configuration

Rules

  • Tests-first: Run pytest after EVERY change, fix failures immediately
  • Type safety: Use Pydantic models, run Mypy
  • Lint clean: Run Ruff before committing
  • Schema sync: Update JSON schemas in schemas/ when config models change
  • No test-only production code: Keep tests separate from implementation
  • Design decisions: You are the architect—make decisions, escalate only if ambiguous/infeasible/against architecture
  • Commit messages: Clear, concise, reference issue/ticket if applicable. Do not commit without approval.
  • Public files name nothing private: the core, src/plugins/, tests/, docs/, CHANGELOG and READMEs are published with their history -- a line a commit adds stays public after a later commit removes it. There: no plugin of a further root, no private agent or workflow by name ("a plugin", "a caller"), no ticket, book, run or session id, no host, local path or person, no cost of an installation. A test builds its own stand-ins; a note that needs those names belongs on the private side.

Testing Strategy

# Test a specific plugin
.venv/Scripts/python.exe -m pytest tests/plugins/test_plugin_<name>.py -v

# Test core components
.venv/Scripts/python.exe -m pytest tests/agent/ -v
.venv/Scripts/python.exe -m pytest tests/config/ -v
.venv/Scripts/python.exe -m pytest tests/llm/ -v
.venv/Scripts/python.exe -m pytest tests/tools/ -v
.venv/Scripts/python.exe -m pytest tests/session/ -v

# Test hooks
.venv/Scripts/python.exe -m pytest tests/hooks/ -v

# Integration tests
.venv/Scripts/python.exe -m pytest tests/integration/ -v

Mandatory: Never run all tests unless absolutely necessary. Prefer targeted tests or groups for speed. Complete test run takes 20mins+.

Overview

  • Load README.md for a general overview.

Work step-by-step until task is fully completed. No intermediate reports.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.