---
name: Skill Editor
description: View, edit, and create skills for this environment. Use this when users want to improve, customize, or create new skills based on learnings from this task.
argument-hint: list | view <skill-id> | update <skill-id> | create <skill-id>
---

# Skill Editor Skill

This skill allows you to view, edit, and create skills for the environment this task is running in. Use this to improve skills based on learnings from the current task, or create new skills when a reusable pattern emerges.

**IMPORTANT**: This skill requires explicit user approval before making any changes. Always explain what changes you're proposing and ask the user to confirm before executing.

**NOTE**: Only skills assigned to this environment can be edited. System skills and read-only skills cannot be modified. New skills can be created and optionally assigned to the current environment.

## Available Commands

### 1. List Editable Skills (`/skill-editor list`)

List all skills assigned to this environment that can be edited.

**When to use:**
- The user wants to see what skills can be modified
- You need to identify which skill to update

### 2. View Skill (`/skill-editor view <skill-id>`)

View a specific skill's full content including frontmatter and body.

**When to use:**
- The user wants to understand a skill's current behavior
- You need to review a skill before proposing changes

### 3. Update Skill (`/skill-editor update <skill-id>`)

Update a skill's content, description, or configuration.

**When to use:**
- The user wants to improve a skill based on task learnings
- A skill's behavior needs refinement
- Documentation or examples need updating

### 4. Create Skill (`/skill-editor create <skill-id>`)

Create a new skill with the specified ID.

**When to use:**
- A reusable pattern has emerged from task work
- The user wants to codify a workflow into a skill
- A new capability should be available for future tasks

**Requirements:**
- Skill ID must be unique and contain only alphanumeric characters, hyphens, and underscores
- Name, description, and body (instructions) are required
- By default, new skills are automatically assigned to the current environment

## How It Works

This skill communicates with the CoderFlow server via the skill management API.

### Environment Variables (automatically set):
- `CODERFLOW_SERVER_URL` - The CoderFlow server URL for API calls
- `TASK_ID` - This task's ID (for authentication)

### API Endpoints:
- `GET /api/skill-management/skills` - List editable skills
- `POST /api/skill-management/skills` - Create a new skill
- `GET /api/skill-management/skills/:skillId` - Get skill details
- `PATCH /api/skill-management/skills/:skillId` - Update skill
- `GET /api/skill-management/skills/:skillId/files/*` - Read supporting file
- `PUT /api/skill-management/skills/:skillId/files/*` - Update supporting file

## Skill Structure

Skills consist of:
1. **`SKILL.md`** - The main skill definition with frontmatter and body
2. **Supporting files** - Additional files the skill may reference

### SKILL.md Frontmatter
```yaml
---
name: Display Name
description: Brief description for the skill picker
argument-hint: optional argument examples
model: optional model override (e.g., haiku for fast tasks)
allowed-tools:
  - Read
  - Write
  - Bash
---
```

### SKILL.md Body
The body contains the detailed skill instructions that guide the AI agent.

## Usage Examples

### Listing Skills

```
User: "What skills can I edit?"

Agent: I'll list the editable skills for this environment.

[Executes API call]

Editable skills in this environment:
1. **code-review** - Performs code review with best practices (editable)
2. **test-generator** - Generates unit tests (editable)
3. **documentation** - System documentation skill (read-only)

Would you like to view or modify any of these?
```

### Viewing a Skill

```
User: "Show me the code-review skill"

Agent: I'll fetch the code-review skill details.

[Executes API call]

**code-review** skill:
- Description: Performs code review with best practices
- Model: (default)
- Allowed tools: Read, Grep, Glob

**Instructions:**
```markdown
# Code Review Skill

Review the specified code for:
- Code quality and readability
- Potential bugs
- Performance issues
- Security concerns
...
```

Would you like to update this skill?
```

### Updating a Skill

```
User: "Add security review to the code-review skill"

Agent: I'll help you update the code-review skill. Let me fetch the current content first...

[Fetches skill]

I propose updating the skill body to include a dedicated security review section:

```diff
# Code Review Skill

Review the specified code for:
- Code quality and readability
- Potential bugs
- Performance issues
- Security concerns

+## Security Review Checklist
+- [ ] Input validation
+- [ ] SQL injection prevention
+- [ ] XSS prevention
+- [ ] Authentication/authorization checks
+- [ ] Sensitive data handling
+- [ ] Dependency vulnerabilities
```

Would you like me to apply this update? (Please confirm)

User: "Yes, update it"

Agent: [Executes API call]
Skill "code-review" updated successfully!
```

### Creating a Skill

```
User: "I keep doing the same database migration workflow. Can you create a skill for it?"

Agent: I'll help you create a new skill for database migrations. Based on the workflow we've been using, here's what I propose:

**Skill ID:** `db-migration`
**Name:** Database Migration
**Description:** Run and validate database migrations with rollback support

**Instructions:**
```markdown
# Database Migration Skill

Guide the user through database migration workflows:
1. Check pending migrations
2. Create backup before migration
3. Run migrations
4. Validate schema changes
5. Provide rollback instructions if needed
...
```

Would you like me to create this skill? (Please confirm)

User: "Yes, create it"

Agent: [Executes API call]
Skill "db-migration" created successfully and assigned to this environment!
```

## Implementation

### List Editable Skills
```bash
curl -s "${CODERFLOW_SERVER_URL}/api/skill-management/skills" \
  -H "X-Task-Id: ${TASK_ID}"
```

**Response:**
```json
{
  "skills": [
    {"id": "code-review", "name": "Code Review", "description": "...", "editable": true}
  ],
  "environment": "my-environment"
}
```

### Get Skill Details
```bash
curl -s "${CODERFLOW_SERVER_URL}/api/skill-management/skills/code-review" \
  -H "X-Task-Id: ${TASK_ID}"
```

**Response:**
```json
{
  "id": "code-review",
  "name": "Code Review",
  "description": "Performs code review with best practices",
  "body": "# Code Review Skill\n\n...",
  "allowed-tools": ["Read", "Grep", "Glob"],
  "model": null,
  "argument-hint": null,
  "files": [{"name": "checklist.md", "type": "file"}],
  "environment": "my-environment"
}
```

### Update Skill
```bash
curl -s -X PATCH "${CODERFLOW_SERVER_URL}/api/skill-management/skills/code-review" \
  -H "Content-Type: application/json" \
  -H "X-Task-Id: ${TASK_ID}" \
  -d '{
    "description": "Updated description",
    "body": "# Updated Code Review Skill\n\n..."
  }'
```

**Response:**
```json
{
  "success": true,
  "id": "code-review",
  "environment": "my-environment",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

### Create Skill
```bash
curl -s -X POST "${CODERFLOW_SERVER_URL}/api/skill-management/skills" \
  -H "Content-Type: application/json" \
  -H "X-Task-Id: ${TASK_ID}" \
  -d '{
    "id": "db-migration",
    "name": "Database Migration",
    "description": "Run and validate database migrations with rollback support",
    "body": "# Database Migration Skill\n\nGuide the user through...",
    "allowed-tools": ["Bash", "Read", "Write"],
    "assignToEnvironment": true
  }'
```

**Response:**
```json
{
  "success": true,
  "id": "db-migration",
  "environment": "my-environment",
  "createdAt": "2024-01-15T10:30:00Z",
  "createdByTaskId": "task-123",
  "createdByUserId": "user-456",
  "assigned": true
}
```

### Read Supporting File
```bash
curl -s "${CODERFLOW_SERVER_URL}/api/skill-management/skills/code-review/files/checklist.md" \
  -H "X-Task-Id: ${TASK_ID}"
```

### Update Supporting File
```bash
curl -s -X PUT "${CODERFLOW_SERVER_URL}/api/skill-management/skills/code-review/files/examples.md" \
  -H "Content-Type: application/json" \
  -H "X-Task-Id: ${TASK_ID}" \
  -d '{
    "content": "# Examples\n\n..."
  }'
```

## Important Notes

1. **User Approval Required**: Never execute creates or updates without explicit user confirmation
2. **Environment Scope**: Only skills assigned to this environment can be edited. New skills can be created and optionally assigned.
3. **Read-Only Skills**: System skills and imported read-only skills cannot be modified
4. **Preserve Functionality**: When updating, ensure the skill still works correctly
5. **Test Changes**: Consider testing skill changes in a safe context
6. **Document Changes**: Update the description if the skill's purpose changes
7. **Supporting Files**: Skills may have supporting files that can also be edited
8. **Skill ID Format**: When creating skills, use lowercase alphanumeric characters with hyphens (e.g., `my-new-skill`)
9. **Auto-Assignment**: New skills are automatically assigned to the current environment by default (use `assignToEnvironment: false` to skip)
