# debatewiki opencode plugin - Skills Usage Guide

## Overview

This document provides detailed usage instructions for the debatewiki opencode plugin skills following the agentskills.io standard. Each skill is designed to be used independently or as part of a larger workflow.

## Skills Registry

The complete skills registry is available in `SKILLS_REGISTRY.yaml` and defines all available skills with their parameters, input/output formats, and usage examples.

## Available Skills

### 1. consensus-voting

**Description**: Calculates voting consensus among agents with configurable threshold

**Execution Path**: `./consensus-skill.js` with function `calculateVotingConsensus`

**Input Format**:
```json
{
  "messages": [
    {
      "agent_name": "string",
      "content": "string"
    }
  ],
  "threshold": "number (0-1, default: 0.7)"
}
```

**Output Format**:
```json
{
  "achieved": "boolean",
  "agreement_ratio": "number (0-1)",
  "summary": "string",
  "votes": "object"
}
```

**Usage Example**:
```bash
node consensus-skill.js calculateVotingConsensus '{"messages": [{"agent_name": "proponent", "content": "vote: yes"}, {"agent_name": "opponent", "content": "vote: no"}, {"agent_name": "moderator", "content": "vote: yes"}], "threshold": 0.6}'
```

### 2. consensus-deliberation

**Description**: Calculates deliberation consensus through multi-round discussions

**Execution Path**: `./consensus-skill.js` with function `calculateDeliberationConsensus`

**Input Format**:
```json
{
  "messages": [
    {
      "agent_name": "string",
      "content": "string"
    }
  ],
  "max_rounds": "number (default: 10)",
  "convergence_threshold": "number (0-1, default: 0.85)"
}
```

**Output Format**:
```json
{
  "achieved": "boolean",
  "agreement_ratio": "number (0-1)",
  "summary": "string",
  "convergence_history": "array<number>",
  "rounds_count": "number"
}
```

**Usage Example**:
```bash
node consensus-skill.js calculateDeliberationConsensus '{"messages": [{"agent_name": "agent1", "content": "round: 1, stance: support"}, {"agent_name": "agent2", "content": "round: 1, stance: oppose"}], "max_rounds": 5, "convergence_threshold": 0.8}'
```

### 3. extract-votes

**Description**: Extracts votes from agent messages

**Execution Path**: `./consensus-skill.js` with function `extractVotes`

**Input Format**:
```json
{
  "messages": [
    {
      "agent_name": "string",
      "content": "string"
    }
  ]
}
```

**Output Format**:
```json
{
  "votes": "object"
}
```

**Usage Example**:
```bash
node consensus-skill.js extractVotes '{"messages": [{"agent_name": "proponent", "content": "I vote yes on this proposal"}, {"agent_name": "opponent", "content": "My vote is no"}]}'
```

### 4. extract-positions

**Description**: Extracts positions/stances from agent messages

**Execution Path**: `./consensus-skill.js` with function `extractStances`

**Input Format**:
```json
{
  "messages": [
    {
      "agent_name": "string",
      "content": "string"
    }
  ]
}
```

**Output Format**:
```json
{
  "stances": "object"
}
```

**Usage Example**:
```bash
node consensus-skill.js extractStances '{"messages": [{"agent_name": "agent1", "content": "My stance is support for this idea"}, {"agent_name": "agent2", "content": "I oppose this proposal"}]}'
```

## When to Use Each Skill

### consensus-voting
- **When**: You need to determine if a simple majority or threshold-based agreement has been reached
- **Best for**: Quick decision making, binary choices, yes/no votes
- **Trigger**: When agents have expressed clear positions that can be counted as votes

### consensus-deliberation
- **When**: You need to evaluate convergence over multiple rounds of discussion
- **Best for**: Complex topics requiring iterative refinement, multi-stage negotiations
- **Trigger**: When agents engage in multi-round discussions with evolving positions

### extract-votes
- **When**: You need to parse agent messages to identify voting patterns
- **Best for**: Pre-processing before consensus calculation, vote auditing
- **Trigger**: Before running any consensus algorithm

### extract-positions
- **When**: You need to identify agent stances in ongoing discussions
- **Best for**: Analyzing multi-agent positions, tracking opinion changes
- **Trigger**: During deliberation processes to monitor agent positions

## Integration with OpenCode

These skills can be integrated into OpenCode workflows through:

1. **Custom Commands**: Create commands that call these skills
2. **Agent Workflows**: Use as part of multi-agent processes
3. **Automated Pipelines**: Integrate into automated decision-making workflows

## Error Handling

Each skill implements proper error handling:

- Invalid input parameters will return descriptive error messages
- Missing required fields will be reported with expected schema
- Processing errors will include context information

## Performance Considerations

- All skills are designed to be lightweight and fast
- Memory usage scales linearly with input size
- Time complexity is generally O(n) where n is the number of messages

## Security Considerations

- Input validation is performed on all parameters
- No external dependencies are required for core functionality
- All processing occurs locally without network access
- Sanitized output prevents injection attacks

## Testing the Skills

Each skill can be tested individually:

```bash
# Test voting consensus
node consensus-skill.js calculateVotingConsensus '{"messages": [{"agent_name": "test", "content": "vote: yes"}]}'

# Test deliberation consensus
node consensus-skill.js calculateDeliberationConsensus '{"messages": [{"agent_name": "test", "content": "round: 1, stance: support"}]}'

# Test vote extraction
node consensus-skill.js extractVotes '{"messages": [{"agent_name": "test", "content": "vote: yes"}]}'

# Test stance extraction
node consensus-skill.js extractStances '{"messages": [{"agent_name": "test", "content": "stance: support"}]}'
```

## Troubleshooting

### Common Issues

1. **Invalid JSON input**: Ensure all inputs are valid JSON with proper escaping
2. **Missing required fields**: Check that all required fields are present in input
3. **Function not found**: Verify the function name matches available functions

### Debugging

For debugging, you can run the skills with verbose output:
```bash
node --inspect consensus-skill.js calculateVotingConsensus '{"messages": []}'
```

## Updating Skills

To update skills:
1. Modify the implementation in `consensus-skill.js`
2. Update the corresponding YAML specification in `SKILLS_REGISTRY.yaml`
3. Update this usage guide with any changes to parameters or behavior
4. Test the updated skill with sample inputs