skillscokac 1.0.0 → 1.3.0

package/README.md

@@ -30,6 +30,9 @@ The CLI will:
 |---------|-------------|
 | `-i, --install-skill <skillName>` | Install a single skill |
 | `-c, --install-collection <collectionId>` | Install all skills from a collection |
+| `-d, --download <skillName> [path]` | Download a skill to a directory (defaults to current directory) |
+| `-u, --upload <skillDir>` | Upload a skill to skills.cokac.com (requires `--apikey`) |
+| `--apikey <key>` | API key for uploading skills |
 | `-l, --list-installed-skills` | List all installed skills |
 | `-r, --remove-skill <skillName>` | Remove an installed skill (with confirmation) |
 | `-f, --remove-skill-force <skillName>` | Remove a skill without confirmation |
@@ -48,6 +51,24 @@ npx skillscokac -i my-awesome-skill
 npx skillscokac -c collection-id-here
 ```
 
+**Download a skill to a specific directory:**
+```bash
+# Download to a specific path
+npx skillscokac -d my-awesome-skill ./downloads
+
+# Download to current directory (path is optional)
+npx skillscokac -d my-awesome-skill
+```
+
+This will download the skill without installing it to Claude Code's skill directories.
+
+**Upload a skill to skills.cokac.com:**
+```bash
+npx skillscokac --upload ./my-skill --apikey ck_live_xxxxx
+```
+
+This will upload your skill to the marketplace. Requires an API key from skills.cokac.com.
+
 **List installed skills:**
 ```bash
 npx skillscokac -l
@@ -77,6 +98,97 @@ When installing, you'll be prompted to choose between:
 - **Scope**: Available only in the current project
 - **Use case**: Project-specific skills or testing before making them global
 
+## Download to Custom Location
+
+If you want to download a skill without installing it to Claude Code's skill directories, use the download command:
+
+```bash
+npx skillscokac -d <skill-name> [path]
+```
+
+The `path` parameter is optional and defaults to the current directory.
+
+**Examples:**
+```bash
+# Download to current directory
+npx skillscokac -d my-skill
+
+# Download to specific path
+npx skillscokac -d my-skill ./my-downloads
+
+# Download to absolute path
+npx skillscokac -d my-skill /path/to/directory
+```
+
+This will:
+1. Fetch the skill from skills.cokac.com
+2. Display skill information
+3. Download all skill files to `<path>/my-skill/`
+4. **Not** install it to Claude Code's skill directories
+
+**Use cases:**
+- Inspecting skill contents before installation
+- Backing up skills locally
+- Sharing skill files with team members
+- Custom deployment workflows
+
+## Upload Skills to Marketplace
+
+You can upload your own skills to skills.cokac.com using the upload command:
+
+```bash
+npx skillscokac --upload <skillDir> --apikey <your-api-key>
+```
+
+### Requirements
+
+1. **API Key**: Get your API key from [skills.cokac.com](https://skills.cokac.com) (format: `ck_live_xxxxx`)
+2. **SKILL.md**: Your skill directory must contain a `SKILL.md` file with frontmatter:
+
+```markdown
+---
+name: my-skill
+description: A brief description of what this skill does
+version: 1.0.0
+---
+
+# My Skill
+
+Your skill instructions here...
+```
+
+### Upload Process
+
+The CLI will:
+1. Parse the `SKILL.md` file and extract metadata (name, description)
+2. Create a new skill post on skills.cokac.com
+3. Upload all additional files in the directory (excluding hidden files and common ignore patterns)
+4. Return the skill URL
+
+### Example
+
+```bash
+# Upload a skill from current directory
+npx skillscokac --upload . --apikey ck_live_xxxxx
+
+# Upload a skill from specific directory
+npx skillscokac --upload ./skills/my-awesome-skill --apikey ck_live_xxxxx
+```
+
+### What Gets Uploaded
+
+- **SKILL.md**: Main skill file (required, used as primary content)
+- **Additional files**: Any other files in the directory (e.g., scripts, configs, examples)
+- **Excluded**: Hidden files (`.git`, `.env`), `node_modules`, `__pycache__`
+
+### API Key
+
+To get an API key:
+1. Visit [skills.cokac.com](https://skills.cokac.com)
+2. Sign in to your account
+3. Go to Settings → API Keys
+4. Generate a new API key
+
 ## Using Installed Skills
 
 After installation, use the skill in Claude Code with:
@@ -166,11 +278,13 @@ When you install a skill, the CLI downloads and extracts:
 
 This CLI communicates with the following endpoints:
 
-| Endpoint | Purpose |
-|----------|---------|
-| `GET /api/marketplace` | Fetch marketplace data to find skills |
-| `GET /api/posts/{postId}/export-skill-zip` | Download skill ZIP package |
-| `GET /api/collections/{collectionId}` | Fetch collection metadata and skills |
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/marketplace` | GET | Fetch marketplace data to find skills |
+| `/api/posts/{postId}/export-skill-zip` | GET | Download skill ZIP package |
+| `/api/collections/{collectionId}` | GET | Fetch collection metadata and skills |
+| `/api/posts` | POST | Create a new skill (requires API key) |
+| `/api/posts/{postId}/files` | POST | Upload additional files to a skill (requires API key) |
 
 **Base URL**: `https://skills.cokac.com`
 

package/bin/skillscokac.js

@@ -18,6 +18,45 @@ const VERSION = packageJson.version
 
 const API_BASE_URL = 'https://skills.cokac.com'
 
+// Configuration constants
+const MAX_ZIP_SIZE = 50 * 1024 * 1024 // 50MB
+const MAX_FILE_SIZE = 5 * 1024 * 1024 // 5MB
+const AXIOS_TIMEOUT = 30000 // 30 seconds
+
+/**
+ * Validate skill name for security
+ */
+function validateSkillName(skillName) {
+  if (!skillName || typeof skillName !== 'string') {
+    throw new Error('Invalid skill name')
+  }
+
+  const trimmed = skillName.trim()
+
+  if (trimmed.length === 0) {
+    throw new Error('Skill name cannot be empty')
+  }
+
+  if (trimmed.includes('/') || trimmed.includes('\\')) {
+    throw new Error('Skill name cannot contain path separators')
+  }
+
+  if (trimmed.includes('..')) {
+    throw new Error('Skill name cannot contain ".."')
+  }
+
+  if (trimmed.startsWith('.')) {
+    throw new Error('Skill name cannot start with a dot')
+  }
+
+  // Check for other potentially dangerous characters
+  if (/[<>:"|?*\x00-\x1f]/.test(trimmed)) {
+    throw new Error('Skill name contains invalid characters')
+  }
+
+  return trimmed
+}
+
 /**
  * Parse frontmatter from markdown content
  */
@@ -79,12 +118,16 @@ async function fetchSkill(skillName, options = {}) {
   const spinner = silent ? null : ora(`Searching for skill: ${skillName}`).start()
 
   try {
+    // Validate skill name
+    skillName = validateSkillName(skillName)
+
     // Step 1: Get marketplace data to find postId
     if (spinner) spinner.text = 'Fetching marketplace data...'
     const marketplaceResponse = await axios.get(`${API_BASE_URL}/api/marketplace`, {
       headers: {
         'User-Agent': `skillscokac-cli/${VERSION}`
-      }
+      },
+      timeout: AXIOS_TIMEOUT
     })
 
     const marketplace = marketplaceResponse.data
@@ -125,15 +168,34 @@ async function fetchSkill(skillName, options = {}) {
         responseType: 'arraybuffer',
         headers: {
           'User-Agent': `skillscokac-cli/${VERSION}`
-        }
+        },
+        timeout: AXIOS_TIMEOUT,
+        maxContentLength: MAX_ZIP_SIZE
       }
     )
 
+    // Check ZIP file size
+    const zipSize = zipResponse.data.byteLength
+    if (zipSize > MAX_ZIP_SIZE) {
+      throw new Error(`Skill package too large (${Math.round(zipSize / 1024 / 1024)}MB). Maximum: ${Math.round(MAX_ZIP_SIZE / 1024 / 1024)}MB`)
+    }
+
     // Step 3: Extract ZIP
     if (spinner) spinner.text = 'Extracting files...'
     const zip = new AdmZip(Buffer.from(zipResponse.data))
     const zipEntries = zip.getEntries()
 
+    // Check total uncompressed size
+    let totalSize = 0
+    for (const entry of zipEntries) {
+      if (!entry.isDirectory) {
+        totalSize += entry.header.size
+        if (totalSize > MAX_ZIP_SIZE * 2) {
+          throw new Error('Skill package contains too much data (possible zip bomb)')
+        }
+      }
+    }
+
     // Find SKILL.md
     const skillMdEntry = zipEntries.find(entry =>
       entry.entryName.endsWith('SKILL.md') && !entry.isDirectory
@@ -309,6 +371,14 @@ async function installSkill(skill, installType, options = {}) {
  * Install skill command handler
  */
 async function installSkillCommand(skillName) {
+  // Validate skill name (fetchSkill also validates, but do it early)
+  try {
+    skillName = validateSkillName(skillName)
+  } catch (error) {
+    console.log(chalk.red(`✗ ${error.message}`))
+    process.exit(1)
+  }
+
   // Fetch skill
   const skill = await fetchSkill(skillName)
 
@@ -333,7 +403,8 @@ async function installCollectionCommand(collectionId) {
     const response = await axios.get(`${API_BASE_URL}/api/collections/${collectionId}`, {
       headers: {
         'User-Agent': `skillscokac-cli/${VERSION}`
-      }
+      },
+      timeout: AXIOS_TIMEOUT
     })
 
     const collection = response.data
@@ -468,6 +539,14 @@ function getSkillsFromDirectory(skillsDir) {
  * Remove skill command handler
  */
 async function removeSkillCommand(skillName, force = false) {
+  // Validate skill name
+  try {
+    skillName = validateSkillName(skillName)
+  } catch (error) {
+    console.log(chalk.red(`✗ ${error.message}`))
+    process.exit(1)
+  }
+
   // Check if skill exists in personal and/or project directories
   const personalSkillDir = path.join(os.homedir(), '.claude', 'skills', skillName)
   const projectSkillDir = path.join(process.cwd(), '.claude', 'skills', skillName)
@@ -675,6 +754,91 @@ async function removeAllSkillsCommand(force = false) {
   }
 }
 
+/**
+ * Download skill command handler
+ */
+async function downloadSkillCommand(skillName, downloadPath) {
+  // Validate skill name (fetchSkill also validates, but do it early)
+  try {
+    skillName = validateSkillName(skillName)
+  } catch (error) {
+    console.log(chalk.red(`✗ ${error.message}`))
+    process.exit(1)
+  }
+
+  // Use current directory if no path specified
+  if (!downloadPath) {
+    downloadPath = process.cwd()
+  }
+
+  // Fetch skill
+  const skill = await fetchSkill(skillName)
+
+  // Display skill info
+  displaySkillInfo(skill)
+  console.log()
+
+  // Resolve download path
+  const resolvedPath = path.resolve(downloadPath)
+  const targetDir = path.join(resolvedPath, skill.skillName)
+
+  const spinner = ora('Downloading skill...').start()
+
+  try {
+    // Create target directory
+    if (fs.existsSync(targetDir)) {
+      spinner.text = 'Removing existing directory...'
+      fs.rmSync(targetDir, { recursive: true, force: true })
+    }
+
+    spinner.text = 'Creating directory...'
+    fs.mkdirSync(targetDir, { recursive: true })
+
+    // Write SKILL.md
+    spinner.text = 'Writing files...'
+    const skillMdPath = path.join(targetDir, 'SKILL.md')
+    fs.writeFileSync(skillMdPath, skill.skillMd || '', 'utf8')
+
+    // Write additional files
+    if (skill.files && skill.files.length > 0) {
+      for (const file of skill.files) {
+        // Security: Prevent path traversal attacks
+        const normalizedPath = path.normalize(file.path).replace(/^(\.\.(\/|\\|$))+/, '')
+        const filePath = path.join(targetDir, normalizedPath)
+
+        // Verify that the final path is still within targetDir
+        const resolvedFilePath = path.resolve(filePath)
+        const resolvedTargetDir = path.resolve(targetDir)
+
+        if (!resolvedFilePath.startsWith(resolvedTargetDir + path.sep) && resolvedFilePath !== resolvedTargetDir) {
+          console.warn(chalk.yellow(`⚠ Skipping potentially unsafe file path: ${file.path}`))
+          continue
+        }
+
+        const fileDir = path.dirname(filePath)
+
+        // Create subdirectories if needed
+        if (!fs.existsSync(fileDir)) {
+          fs.mkdirSync(fileDir, { recursive: true })
+        }
+
+        fs.writeFileSync(filePath, file.content || '', 'utf8')
+      }
+    }
+
+    spinner.succeed(chalk.green('Downloaded successfully!'))
+    console.log()
+    console.log(chalk.dim('  Location: ') + chalk.cyan(targetDir))
+    console.log(chalk.dim('  Files: ') + chalk.white(`${1 + (skill.files ? skill.files.length : 0)} file${skill.files && skill.files.length !== 0 ? 's' : ''}`))
+    console.log()
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to download skill'))
+    console.error(chalk.red('\nError:'), error.message)
+    process.exit(1)
+  }
+}
+
 /**
  * List installed skills command handler
  */
@@ -767,6 +931,234 @@ async function listInstalledSkillsCommand() {
   }
 }
 
+/**
+ * Create skill on SkillsCokac API
+ */
+async function createSkill(skillData, apiKey, silent = false) {
+  const payload = {
+    type: 'SKILL',
+    title: skillData.name,
+    description: skillData.description,
+    content: skillData.content,
+    skillMd: skillData.content,
+    visibility: skillData.visibility || 'PUBLIC',
+    tags: skillData.tags || ['claude-code', 'agent-skill']
+  }
+
+  try {
+    const response = await axios.post(`${API_BASE_URL}/api/posts`, payload, {
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+        'User-Agent': `skillscokac-cli/${VERSION}`
+      },
+      timeout: AXIOS_TIMEOUT
+    })
+
+    return response.data
+  } catch (error) {
+    // Handle 409 Conflict (skill name already exists)
+    if (error.response && error.response.status === 409) {
+      if (!silent) {
+        console.log(chalk.red('✗ Skill name already exists. Please choose a different name.'))
+      }
+    } else if (!silent) {
+      console.log(chalk.red('✗ Failed to create skill'))
+      if (error.response) {
+        console.error(chalk.red('  Status:'), error.response.status)
+        console.error(chalk.red('  Response:'), error.response.data)
+      } else {
+        console.error(chalk.red('  Error:'), error.message)
+      }
+    }
+    throw error
+  }
+}
+
+/**
+ * Upload skill files to SkillsCokac API
+ */
+async function uploadSkillFiles(skillId, skillDir, apiKey, silent = false) {
+  let uploadedCount = 0
+  let failedCount = 0
+  const files = []
+
+  // Recursively find all files in the directory
+  function findFiles(dir, baseDir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        // Skip hidden directories and common ignore patterns
+        if (entry.name.startsWith('.') || entry.name === '__pycache__' || entry.name === 'node_modules') {
+          continue
+        }
+        findFiles(fullPath, baseDir)
+      } else if (entry.isFile()) {
+        // Skip SKILL.md at root level (already uploaded as main content)
+        const relativePath = path.relative(baseDir, fullPath)
+        if (relativePath === 'SKILL.md') {
+          continue
+        }
+
+        // Skip hidden files
+        if (entry.name.startsWith('.')) {
+          continue
+        }
+
+        files.push({ fullPath, relativePath })
+      }
+    }
+  }
+
+  try {
+    findFiles(skillDir, skillDir)
+
+    if (files.length === 0) {
+      return { uploadedCount: 0, failedCount: 0 }
+    }
+
+    for (const file of files) {
+      try {
+        // Check file size before reading
+        const stats = fs.statSync(file.fullPath)
+        if (stats.size > MAX_FILE_SIZE) {
+          if (!silent) {
+            console.warn(chalk.yellow(`⚠ Skipping large file (${Math.round(stats.size / 1024 / 1024)}MB): ${file.relativePath}`))
+          }
+          failedCount++
+          continue
+        }
+
+        // Try to read as text
+        let content
+        try {
+          content = fs.readFileSync(file.fullPath, 'utf8')
+        } catch (err) {
+          // Skip binary files
+          continue
+        }
+
+        const filePayload = {
+          path: file.relativePath.replace(/\\/g, '/'), // Normalize Windows paths
+          content: content
+        }
+
+        const response = await axios.post(
+          `${API_BASE_URL}/api/posts/${skillId}/files`,
+          filePayload,
+          {
+            headers: {
+              'Authorization': `Bearer ${apiKey}`,
+              'Content-Type': 'application/json',
+              'User-Agent': `skillscokac-cli/${VERSION}`
+            },
+            timeout: AXIOS_TIMEOUT
+          }
+        )
+
+        if (response.status === 201) {
+          uploadedCount++
+        } else {
+          failedCount++
+        }
+      } catch (error) {
+        failedCount++
+      }
+    }
+
+    return { uploadedCount, failedCount }
+  } catch (error) {
+    if (!silent) {
+      console.error(chalk.red('Failed to upload files'))
+    }
+    throw error
+  }
+}
+
+/**
+ * Upload skill command handler
+ */
+async function uploadSkillCommand(skillDir, apiKey) {
+  // Validate API key
+  if (!apiKey) {
+    console.log(chalk.red('✗ API key is required'))
+    console.log(chalk.dim('Usage: npx skillscokac --upload <skillDir> --apikey <key>'))
+    console.log()
+    process.exit(1)
+  }
+
+  // Resolve skill directory
+  const resolvedSkillDir = path.resolve(skillDir)
+  const skillMdPath = path.join(resolvedSkillDir, 'SKILL.md')
+
+  // Validate directory exists
+  if (!fs.existsSync(resolvedSkillDir)) {
+    console.log(chalk.red(`✗ Directory not found: ${resolvedSkillDir}`))
+    console.log()
+    process.exit(1)
+  }
+
+  // Validate SKILL.md exists
+  if (!fs.existsSync(skillMdPath)) {
+    console.log(chalk.red(`✗ SKILL.md not found in: ${resolvedSkillDir}`))
+    console.log(chalk.dim('  The skill directory must contain a SKILL.md file'))
+    console.log()
+    process.exit(1)
+  }
+
+  let spinner
+  try {
+    // Step 1: Parse SKILL.md
+    spinner = ora('Uploading skill...').start()
+    const skillMdContent = fs.readFileSync(skillMdPath, 'utf8')
+    const { metadata } = parseFrontmatter(skillMdContent)
+
+    if (!metadata.name) {
+      spinner.fail(chalk.red('SKILL.md must have a "name" in frontmatter'))
+      process.exit(1)
+    }
+
+    if (!metadata.description) {
+      spinner.fail(chalk.red('SKILL.md must have a "description" in frontmatter'))
+      process.exit(1)
+    }
+
+    const skillData = {
+      name: metadata.name,
+      description: metadata.description,
+      content: skillMdContent,
+      visibility: 'PUBLIC',
+      tags: ['claude-code', 'agent-skill']
+    }
+
+    // Step 2: Create skill
+    spinner.text = 'Creating skill...'
+    const skill = await createSkill(skillData, apiKey, true)
+
+    // Step 3: Upload additional files
+    spinner.text = 'Uploading files...'
+    const { uploadedCount, failedCount } = await uploadSkillFiles(skill.id, resolvedSkillDir, apiKey, true)
+
+    // Success summary
+    const fileInfo = uploadedCount > 0 ? ` (${uploadedCount} file${uploadedCount !== 1 ? 's' : ''})` : ''
+    spinner.succeed(chalk.green(`Uploaded: ${skillData.name}${fileInfo}`))
+    console.log(chalk.cyan(`https://skills.cokac.com/p/${skill.id}`))
+
+  } catch (error) {
+    if (spinner) spinner.stop()
+    // Handle 409 Conflict (skill name already exists)
+    if (error.response && error.response.status === 409) {
+      console.log(chalk.red('✗ Skill name already exists. Please choose a different name.'))
+    } else {
+      console.error(chalk.red('✗ Upload failed:'), error.message)
+    }
+    process.exit(1)
+  }
+}
+
 /**
  * Setup CLI with Commander
  */
@@ -780,6 +1172,9 @@ program
 program
   .option('-i, --install-skill <skillName>', 'Install a skill by name')
   .option('-c, --install-collection <collectionId>', 'Install all skills from a collection')
+  .option('-d, --download <args...>', 'Download a skill to a directory (usage: --download <skillName> [path], defaults to current directory)')
+  .option('-u, --upload <skillDir>', 'Upload a skill from a directory (requires --apikey)')
+  .option('--apikey <key>', 'API key for uploading skills')
   .option('-r, --remove-skill <skillName>', 'Remove an installed skill')
   .option('-f, --remove-skill-force <skillName>', 'Remove skill from all locations without confirmation')
   .option('-a, --remove-all-skills', 'Remove all installed skills')
@@ -796,6 +1191,18 @@ const options = program.opts()
       await installSkillCommand(options.installSkill)
     } else if (options.installCollection) {
       await installCollectionCommand(options.installCollection)
+    } else if (options.download) {
+      // Download expects one or two arguments: skillName and optional path
+      if (options.download.length < 1 || options.download.length > 2) {
+        console.log(chalk.red('✗ Invalid arguments for --download'))
+        console.log(chalk.dim('Usage: npx skillscokac --download <skillName> [path]'))
+        console.log()
+        process.exit(1)
+      }
+      const [skillName, downloadPath] = options.download
+      await downloadSkillCommand(skillName, downloadPath)
+    } else if (options.upload) {
+      await uploadSkillCommand(options.upload, options.apikey)
     } else if (options.removeAllSkillsForce) {
       await removeAllSkillsCommand(true)
     } else if (options.removeAllSkills) {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "skillscokac",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "description": "CLI tool to install and manage Claude Code skills from skills.cokac.com",
   "main": "bin/skillscokac.js",
   "bin": {
-    "skillscokac": "./bin/skillscokac.js"
+    "skillscokac": "bin/skillscokac.js"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -30,7 +30,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/kstost/skillscokac.git"
+    "url": "git+https://github.com/kstost/skillscokac.git"
   },
   "bugs": {
     "url": "https://github.com/kstost/skillscokac/issues"