@profoundlogic/coderflow-server 0.2.8 → 0.3.0

package/dist/shipped-skills/skill-editor/SKILL.md

@@ -1,87 +1,114 @@
 ---
 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>
+description: Full CRUD management for environment skills and their files, including create, update, delete, and unassign operations.
+argument-hint: list | view <skill-id> | create <skill-id> | update <skill-id> | delete <skill-id> [--force] [--unassign-only] | file list <skill-id> | file read <skill-id> <path> | file write <skill-id> <path> | file delete <skill-id> <path>
 ---
 
 # 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.
+This skill provides full management for skills assigned to the current environment:
+- Skill-level operations: list, view, create, update, delete, and unassign
+- File-level operations: list, read, create/update, and delete for supporting files
 
-**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.
+Use this when users want direct control over skill behavior and skill file contents.
 
-**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.
+## Scope And Guardrails
 
-## Available Commands
+- This skill can only modify non-read-only skills that are assigned to the current environment.
+- System skills and read-only imported skills are blocked by the API.
+- Use explicit user intent for destructive operations (`delete` at skill level, recursive directory deletion at file level).
+- If user intent is already clear and explicit, execute directly; do not add unnecessary confirmation loops.
 
-### 1. List Editable Skills (`/skill-editor list`)
+## Available Commands
 
-List all skills assigned to this environment that can be edited.
+### 1. List Skills (`/skill-editor list`)
 
-**When to use:**
-- The user wants to see what skills can be modified
-- You need to identify which skill to update
+List editable skills assigned to the current environment.
 
 ### 2. View Skill (`/skill-editor view <skill-id>`)
 
-View a specific skill's full content including frontmatter and body.
+Fetch skill metadata and body from `SKILL.md`, plus top-level supporting entries.
+
+### 3. Create Skill (`/skill-editor create <skill-id>`)
 
-**When to use:**
-- The user wants to understand a skill's current behavior
-- You need to review a skill before proposing changes
+Create a new skill with required fields:
+- `id`
+- `name`
+- `description`
+- `body`
 
-### 3. Update Skill (`/skill-editor update <skill-id>`)
+Optional:
+- `allowed-tools`
+- `model`
+- `argument-hint`
+- `assignToEnvironment` (default `true`)
 
-Update a skill's content, description, or configuration.
+### 4. Update Skill (`/skill-editor update <skill-id>`)
 
-**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
+Patch one or more fields on `SKILL.md` frontmatter/body:
+- `name`
+- `description`
+- `body`
+- `allowed-tools`
+- `model`
+- `argument-hint`
 
-### 4. Create Skill (`/skill-editor create <skill-id>`)
+### 5. Delete Or Unassign Skill (`/skill-editor delete <skill-id> [--force] [--unassign-only]`)
 
-Create a new skill with the specified ID.
+Two supported modes:
+- `delete` (default): remove the skill directory and unassign it from environments
+- `unassign`: remove the skill from only the current environment, keep files on disk
 
-**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
+Rules:
+- If deleting a skill that is assigned to other environments, `force=true` is required.
+- Without `force`, delete is limited to the current environment.
 
-**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
+### 6. File Operations
+
+- List files from skill details: `/skill-editor file list <skill-id>`
+- Read file: `/skill-editor file read <skill-id> <path>`
+- Write file: `/skill-editor file write <skill-id> <path>`
+- Delete file or directory: `/skill-editor file delete <skill-id> <path>`
+
+Notes:
+- `PUT` creates parent directories automatically.
+- `DELETE` supports files and directories (directories are recursive).
+- `SKILL.md` must be modified via skill update (`PATCH /skills/:skillId`) and cannot be deleted via file delete endpoint.
 
 ## How It Works
 
-This skill communicates with the CoderFlow server via the skill management API.
+This skill uses the task-scoped skill management API.
+
+### Environment Variables
 
-### Environment Variables (automatically set):
-- `CODERFLOW_SERVER_URL` - The CoderFlow server URL for API calls
-- `TASK_ID` - This task's ID (for authentication)
+- `CODERFLOW_SERVER_URL` - Base URL for CoderFlow server
+- `TASK_ID` - Task identifier used for auth (`X-Task-Id`)
+
+### API Endpoints
 
-### API Endpoints:
 - `GET /api/skill-management/skills` - List editable skills
-- `POST /api/skill-management/skills` - Create a new skill
+- `POST /api/skill-management/skills` - Create a skill
 - `GET /api/skill-management/skills/:skillId` - Get skill details
 - `PATCH /api/skill-management/skills/:skillId` - Update skill
+- `DELETE /api/skill-management/skills/:skillId` - Delete or unassign skill (`mode`, `force`)
 - `GET /api/skill-management/skills/:skillId/files/*` - Read supporting file
-- `PUT /api/skill-management/skills/:skillId/files/*` - Update supporting file
+- `PUT /api/skill-management/skills/:skillId/files/*` - Create/update supporting file
+- `DELETE /api/skill-management/skills/:skillId/files/*` - Delete supporting file or directory
 
 ## 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
+Each skill is a directory under `skills/<skill-id>/` containing:
+1. `SKILL.md` (required)
+2. Supporting files/directories (optional)
 
 ### 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)
+description: Brief description
+argument-hint: optional argument hints
+model: optional model override
 allowed-tools:
   - Read
   - Write
@@ -90,237 +117,103 @@ allowed-tools:
 ```
 
 ### 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
+The body contains the operative instructions used by the AI.
 
-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
+## Implementation
 
-Review the specified code for:
-- Code quality and readability
-- Potential bugs
-- Performance issues
-- Security concerns
+### List Skills
 
-+## Security Review Checklist
-+- [ ] Input validation
-+- [ ] SQL injection prevention
-+- [ ] XSS prevention
-+- [ ] Authentication/authorization checks
-+- [ ] Sensitive data handling
-+- [ ] Dependency vulnerabilities
+```bash
+curl -s "${CODERFLOW_SERVER_URL}/api/skill-management/skills" \
+  -H "X-Task-Id: ${TASK_ID}"
 ```
 
-Would you like me to apply this update? (Please confirm)
-
-User: "Yes, update it"
+### View Skill
 
-Agent: [Executes API call]
-Skill "code-review" updated successfully!
+```bash
+curl -s "${CODERFLOW_SERVER_URL}/api/skill-management/skills/<skill-id>" \
+  -H "X-Task-Id: ${TASK_ID}"
 ```
 
-### Creating a Skill
+### 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",
+    "body": "# Database Migration Skill\\n\\nGuide the user through...",
+    "allowed-tools": ["Bash", "Read", "Write"],
+    "assignToEnvironment": true
+  }'
 ```
-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
+### Update 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
-...
+```bash
+curl -s -X PATCH "${CODERFLOW_SERVER_URL}/api/skill-management/skills/<skill-id>" \
+  -H "Content-Type: application/json" \
+  -H "X-Task-Id: ${TASK_ID}" \
+  -d '{
+    "description": "Updated description",
+    "body": "# Updated Skill\\n\\n..."
+  }'
 ```
 
-Would you like me to create this skill? (Please confirm)
-
-User: "Yes, create it"
+### Delete Skill (Current Environment)
 
-Agent: [Executes API call]
-Skill "db-migration" created successfully and assigned to this environment!
+```bash
+curl -s -X DELETE "${CODERFLOW_SERVER_URL}/api/skill-management/skills/<skill-id>" \
+  -H "X-Task-Id: ${TASK_ID}"
 ```
 
-## Implementation
+### Force Delete Skill From All Environments
 
-### List Editable Skills
 ```bash
-curl -s "${CODERFLOW_SERVER_URL}/api/skill-management/skills" \
+curl -s -X DELETE "${CODERFLOW_SERVER_URL}/api/skill-management/skills/<skill-id>?force=true" \
   -H "X-Task-Id: ${TASK_ID}"
 ```
 
-**Response:**
-```json
-{
-  "skills": [
-    {"id": "code-review", "name": "Code Review", "description": "...", "editable": true}
-  ],
-  "environment": "my-environment"
-}
-```
+### Unassign Skill Only (Keep Files)
 
-### Get Skill Details
 ```bash
-curl -s "${CODERFLOW_SERVER_URL}/api/skill-management/skills/code-review" \
+curl -s -X DELETE "${CODERFLOW_SERVER_URL}/api/skill-management/skills/<skill-id>?mode=unassign" \
   -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"
-}
-```
+### Read Supporting File
 
-### 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..."
-  }'
+curl -s "${CODERFLOW_SERVER_URL}/api/skill-management/skills/<skill-id>/files/<path>" \
+  -H "X-Task-Id: ${TASK_ID}"
 ```
 
-**Response:**
-```json
-{
-  "success": true,
-  "id": "code-review",
-  "environment": "my-environment",
-  "updatedAt": "2024-01-15T10:30:00Z"
-}
-```
+### Write Supporting File
 
-### Create Skill
 ```bash
-curl -s -X POST "${CODERFLOW_SERVER_URL}/api/skill-management/skills" \
+curl -s -X PUT "${CODERFLOW_SERVER_URL}/api/skill-management/skills/<skill-id>/files/<path>" \
   -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
+    "content": "# Examples\\n\\n..."
   }'
 ```
 
-**Response:**
-```json
-{
-  "success": true,
-  "id": "db-migration",
-  "environment": "my-environment",
-  "createdAt": "2024-01-15T10:30:00Z",
-  "createdByTaskId": "task-123",
-  "createdByUserId": "user-456",
-  "assigned": true
-}
-```
+### Delete Supporting File Or Directory
 
-### Read Supporting File
 ```bash
-curl -s "${CODERFLOW_SERVER_URL}/api/skill-management/skills/code-review/files/checklist.md" \
+curl -s -X DELETE "${CODERFLOW_SERVER_URL}/api/skill-management/skills/<skill-id>/files/<path>" \
   -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)
+1. Preserve valid frontmatter when updating `SKILL.md`.
+2. Prefer precise file paths for file operations (including nested paths).
+3. `SKILL.md` updates must go through skill update endpoint, not file write endpoint.
+4. Skill deletions can affect multiple environments when `force=true`; call this out before execution.
+5. If skill assignment or visibility behavior changes, verify with a follow-up list/view call.