Customization Guide - Plugin Agent Marketplace

Why Customize?

Our plugins are starting points, not endpoints. Every organization has unique needs — coding standards, preferred tools, domain-specific knowledge. Customization lets you train agents that truly understand YOUR workflow.

Customizing Agents

Agent files are Markdown with YAML frontmatter. Edit them to change behavior, personality, and capabilities.

agents/python-expert.md

---
name: python-expert
description: Senior Python developer with deep expertise
model: sonnet
tools: Read, Write, Edit, Bash, Grep, Glob, Task
sasmp_version: "1.3.0"
eqhm_enabled: true
---

# Python Expert Agent

You are a senior Python developer with 10+ years of experience.

## Core Expertise
- Python 3.8+ best practices
- Type hints and mypy
- pytest for testing
- FastAPI for web services

## Your Approach
1. Always write type-annotated code
2. Follow PEP 8 style guidelines
3. Write comprehensive tests
4. Document with docstrings

## Company-Specific Standards
(Add your standards here)

What to Customize

✓ Frontmatter

• name — Agent identifier
• model — haiku, sonnet, opus
• tools — Available capabilities

✓ System Prompt

• Expertise description
• Coding standards
• Response style
• Domain knowledge

Example: Adding Company Standards

Custom Addition

## Company-Specific Standards

### Code Style
- Use black formatter with line-length=100
- Always use ruff for linting
- Prefer pathlib over os.path

### Architecture
- Follow our hexagonal architecture pattern
- Use pydantic for all data models
- Implement repository pattern for data access

### Testing
- Minimum 80% code coverage
- Use pytest-cov for coverage reports
- Mock external services with responses library

### Documentation
- Google-style docstrings
- Document all public APIs
- Include usage examples in docstrings

Creating Custom Skills

Skills are reusable workflows. Use the Golden Format for production-quality skills.

Golden Format Structure

skills/my-custom-skill/
├── SKILL.md              # Skill definition with YAML frontmatter
│
├── assets/               # Real templates and configs
│   ├── config.yaml       # Configuration template
│   ├── schema.json       # Validation schema
│   └── template.py       # Code template
│
├── scripts/              # Automation scripts
│   ├── validate.py       # Validation script
│   ├── generate.sh       # Code generator
│   └── test.py           # Test runner
│
└── references/          # Documentation
    ├── GUIDE.md          # Usage guide
    ├── PATTERNS.md       # Design patterns
    └── EXAMPLES.md       # Example usage

SKILL.md Template

skills/code-review/SKILL.md

---
name: code-review
description: Automated code review with quality checks
sasmp_version: "1.3.0"
bonded_agent: python-expert
bond_type: PRIMARY_BOND
---

# Code Review Skill

Perform comprehensive code review with:
- Style compliance checking
- Security vulnerability scanning
- Performance analysis
- Best practice recommendations

## Usage

```
Skill("code-review", args="src/main.py")
```

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| file | string | File or directory to review |
| strict | boolean | Enable strict mode |

## Output

Returns a detailed review report with:
- Issues found (critical, warning, info)
- Suggestions for improvement
- Example fixes

⚠️ Important: No Empty Placeholders

The Golden Format requires real content in assets/, scripts/, and references/. Empty README.md files or placeholder text will trigger E-code violations (E701-E704).

Adding Custom Commands

Commands are slash-invoked workflows. They provide quick access to common tasks.

commands/lint.md

---
description: Run linters and formatters on Python code
allowed-tools: Bash, Read, Write
---

# Lint Command

Run the following sequence:

1. Format with black
   ```bash
   black --check --line-length=100 .
   ```

2. Lint with ruff
   ```bash
   ruff check .
   ```

3. Type check with mypy
   ```bash
   mypy --strict .
   ```

## Usage

```
/lint
/lint src/
/lint --fix
```

Plugin Configuration

The plugin.json manifest defines your plugin's structure.

.claude-plugin/plugin.json

{
  "name": "custom-plugin-python",
  "version": "1.0.0",
  "description": "Python development agent with custom standards",
  "author": {
    "name": "Your Name",
    "url": "https://github.com/yourname"
  },
  "agents": [
    "./agents/python-expert.md",
    "./agents/python-architect.md"
  ],
  "skills": [
    "./skills/code-review/SKILL.md"
  ],
  "commands": [
    "./commands/lint.md"
  ]
}

Path Requirements

• All paths must start with ./
• Use forward slashes / even on Windows
• Paths are relative to plugin root

Best Practices

✓ Do

• Keep agents focused on specific roles
• Use descriptive, unique names
• Document all customizations
• Test after every change
• Version control your plugins
• Follow Golden Format for skills

✗ Don't

• Create overly broad agents
• Use duplicate names across plugins
• Leave empty placeholder files
• Skip testing after modifications
• Forget to restart Claude Code
• Mix different roles in one agent

Testing Your Changes

1. Validate Plugin Structure

/plugin validate path/to/your/plugin

Checks for structural issues, missing files, and E-code violations.

2. Clear Cache & Restart

rm -rf ~/.claude/plugins/cache/* # Then restart Claude Code

3. Test Agent Invocation

"Use the python-expert agent to review this code"

Verify the agent responds with your customized behavior.

Ready to Share?

If you've created something useful, consider contributing it back to the community!

Learn How to Contribute →