skill-gen 0.0.1

package/README.md

@@ -0,0 +1,90 @@
+# skillify
+
+Generate SKILL.md files for npm packages following [Anthropic's Agent Skills specification](https://agentskills.io/specification).
+
+## Install
+
+```bash
+npm install -g skillify
+```
+
+Or use directly:
+
+```bash
+npx skill-gen .
+```
+
+## Usage
+
+```bash
+# Current directory
+npx skill-gen .
+
+# Specific path
+npx skill-gen ~/projects/my-package
+
+# Print to stdout
+npx skill-gen . --stdout
+
+# Dry run (preview only)
+npx skill-gen . --dry-run
+
+# Custom output path
+npx skill-gen . -o ./docs/SKILL.md
+```
+
+## What it Does
+
+1. Reads `package.json` for name, description, keywords, bin, exports
+2. Analyzes CLI entry point for flags/commands
+3. Extracts exported functions from main module
+4. Generates SKILL.md with:
+   - Proper YAML frontmatter (name, description)
+   - "When to Use" triggers
+   - Quick Start examples
+   - CLI Reference (if applicable)
+   - API Reference (if applicable)
+
+## Output Format
+
+```yaml
+---
+name: my-package
+description: Does X and Y. Use when working with Z.
+---
+
+# my-package
+
+## When to Use
+...
+
+## Quick Start
+...
+```
+
+## Why SKILL.md?
+
+SKILL.md is the [Agent Skills](https://agentskills.io) standard for AI agent documentation:
+
+- **Discoverable**: Agents find skills by name + description
+- **Progressive disclosure**: Metadata loads first, details on-demand
+- **Portable**: Works with Claude Code, Cursor, Copilot, Codex
+
+## Best Practices Applied
+
+Based on [Anthropic's guidelines](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices):
+
+- Third person descriptions ("Builds X" not "I build X")
+- Includes "when to use" triggers
+- Concrete examples over abstract descriptions
+- Under 500 lines for optimal performance
+
+## Related
+
+- [Agent Skills Specification](https://agentskills.io/specification)
+- [Anthropic Skills Repository](https://github.com/anthropics/skills)
+- [fund-agent](https://npmjs.com/package/fund-agent)
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: skillify
+description: Generates SKILL.md files for npm packages following Anthropic's Agent Skills specification. Use when adding agent documentation to an npm package, making a package AI-agent friendly, or creating skills from existing code.
+---
+
+# Skillify
+
+Generate a SKILL.md file for an npm package, making it discoverable and usable by AI agents.
+
+## When to Use
+
+- Adding agent documentation to an npm package
+- Making a library AI-agent friendly
+- Creating a skill from existing CLI tool
+- Preparing a package for the Agent Skills ecosystem
+
+## Quick Start
+
+```bash
+/skillify .                    # Current directory
+/skillify ~/path/to/package    # Local package
+/skillify btctx                # npm package name
+```
+
+## Process
+
+### Step 1: Gather Package Information
+
+Read these files (in order of importance):
+
+1. **package.json** (required)
+   - `name` → skill name (kebab-case)
+   - `description` → base for skill description
+   - `bin` → CLI commands available
+   - `main`/`exports` → API entry points
+   - `keywords` → trigger words
+
+2. **README.md** (if exists)
+   - Usage examples
+   - API documentation
+   - Installation instructions
+
+3. **CLI entry point** (if `bin` exists)
+   - Parse for `--help` output
+   - Extract flags and commands
+
+4. **Main module** (if `main`/`exports` exists)
+   - Exported functions
+   - JSDoc comments
+   - Type definitions
+
+### Step 2: Analyze for Agent Usage
+
+Determine:
+- **What it does** - core functionality in one sentence
+- **When to use** - specific triggers/contexts
+- **How to use** - primary usage pattern (CLI or API)
+- **Examples** - concrete input/output pairs
+
+### Step 3: Generate SKILL.md
+
+Follow this template:
+
+```yaml
+---
+name: <package-name-kebab-case>
+description: <What it does>. <When to use - specific triggers>.
+---
+```
+
+**Description rules:**
+- Third person only ("Builds X" not "I build X")
+- Under 1024 characters
+- Include both WHAT and WHEN
+- Use specific keywords for discovery
+
+**Body structure:**
+
+```markdown
+# <Package Name>
+
+## When to Use
+
+Invoke when you need to:
+- <specific trigger 1>
+- <specific trigger 2>
+- <specific trigger 3>
+
+## Quick Start
+
+<primary usage pattern - CLI or code>
+
+## Examples
+
+**Example 1: <use case>**
+
+Input:
+<concrete input>
+
+Output:
+<concrete output>
+
+## CLI Reference (if applicable)
+
+<flags and commands>
+
+## API Reference (if applicable)
+
+<key exported functions>
+```
+
+### Step 4: Write the File
+
+Save to: `<package-root>/SKILL.md`
+
+## Quality Checklist
+
+Before finalizing, verify:
+
+- [ ] Description is third person
+- [ ] Description includes WHAT and WHEN
+- [ ] Description under 1024 characters
+- [ ] Name is kebab-case, lowercase
+- [ ] Examples are concrete (not abstract)
+- [ ] Body under 500 lines
+- [ ] No time-sensitive information
+- [ ] Consistent terminology
+
+## Description Formula
+
+```
+<Verb>s <object> [details]. Use when <trigger1>, <trigger2>, or <trigger3>.
+```
+
+**Good examples:**
+```yaml
+description: Builds Bitcoin Taproot transactions from inputs and outputs. Use when creating P2TR transactions, spending UTXOs, or working with Taproot addresses.
+```
+
+```yaml
+description: Broadcasts signed Bitcoin transactions to the network. Use when sending transactions to mempool, publishing to testnet4, or checking broadcast status.
+```
+
+**Bad examples:**
+```yaml
+description: Helps with Bitcoin stuff.  # Too vague
+description: I can build transactions.  # Wrong POV
+description: A library for transactions.  # No "when to use"
+```
+
+## Naming Convention
+
+Convert package name to kebab-case:
+
+| package.json name | SKILL.md name |
+|-------------------|---------------|
+| `btctx` | `btctx` |
+| `sendTx` | `send-tx` |
+| `BitcoinBuilder` | `bitcoin-builder` |
+| `@scope/pkg` | `pkg` (drop scope) |
+
+## Example Output
+
+For a package like `btctx`:
+
+```yaml
+---
+name: btctx
+description: Builds Bitcoin Taproot (P2TR) transactions from UTXOs. Use when creating Bitcoin transactions, spending Taproot outputs, or building raw transaction hex.
+---
+
+# btctx
+
+## When to Use
+
+Invoke when you need to:
+- Build a Bitcoin transaction from UTXOs
+- Create Taproot (P2TR) outputs
+- Generate signed transaction hex for broadcasting
+
+## Quick Start
+
+```javascript
+import { buildTx } from 'btctx';
+
+const { hex, txid } = await buildTx({
+  privateKey: '...',
+  publicKey: '...',
+  txid: '<input-txid>',
+  vout: 0,
+  inputAmount: 100000,
+  outputs: [{ pubkey: '<recipient>', amount: 99000 }]
+});
+```
+
+## Examples
+
+**Example: Simple transfer**
+
+Input:
+- 100,000 sats from UTXO
+- Send to one recipient
+
+Output:
+- Signed transaction hex
+- Transaction ID (txid)
+
+## API Reference
+
+### `buildTx(options)`
+
+Builds and signs a Taproot transaction.
+
+Options:
+- `privateKey` - 64-char hex signing key
+- `publicKey` - 64-char hex x-only pubkey
+- `txid` - Input transaction ID
+- `vout` - Output index to spend
+- `inputAmount` - Satoshis in input
+- `outputs` - Array of `{ pubkey, amount }`
+
+Returns: `{ hex, txid }`
+```
+
+## References
+
+- [Agent Skills Specification](https://agentskills.io/specification)
+- [Anthropic Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- [GitHub: anthropics/skills](https://github.com/anthropics/skills)

package/bin/skillify.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+/**
+ * skillify - Generate SKILL.md for npm packages
+ *
+ * Usage:
+ *   npx skill-gen .                  # Current directory
+ *   npx skill-gen ~/path/to/pkg      # Local package
+ *   npx skill-gen btctx              # npm package (fetches info)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// CLI args
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+  console.log(`
+skillify v0.0.1 - Generate SKILL.md for npm packages
+
+Usage:
+  npx skill-gen <path>       Generate SKILL.md for local package
+  npx skill-gen .            Current directory
+
+Options:
+  -h, --help     Show this help
+  -v, --version  Show version
+  -o, --output   Output path (default: ./SKILL.md)
+  --stdout       Print to stdout instead of file
+  --dry-run      Show what would be generated
+
+Examples:
+  npx skill-gen .
+  npx skill-gen ~/projects/my-package
+  npx skill-gen . --stdout
+`);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  console.log('0.0.1');
+  process.exit(0);
+}
+
+// Parse flags
+const stdout = args.includes('--stdout');
+const dryRun = args.includes('--dry-run');
+const outputIdx = args.indexOf('-o') !== -1 ? args.indexOf('-o') : args.indexOf('--output');
+const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
+
+// Get target path
+const targetArg = args.find(a => !a.startsWith('-') && a !== outputPath);
+const targetPath = path.resolve(targetArg || '.');
+
+/**
+ * Convert string to kebab-case
+ */
+function toKebabCase(str) {
+  return str
+    .replace(/^@[^/]+\//, '') // Remove scope
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[_\s]+/g, '-')
+    .toLowerCase();
+}
+
+/**
+ * Extract CLI info from a file
+ */
+function extractCliInfo(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const flags = [];
+
+    // Look for common flag patterns
+    const flagPatterns = [
+      /--(\w[-\w]*)/g,
+      /-([a-zA-Z]),\s*--(\w[-\w]*)/g,
+    ];
+
+    for (const pattern of flagPatterns) {
+      let match;
+      while ((match = pattern.exec(content)) !== null) {
+        flags.push(match[1] || match[2]);
+      }
+    }
+
+    return [...new Set(flags)].filter(f => !['help', 'version'].includes(f));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Extract exports from main module
+ */
+function extractExports(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const exports = [];
+
+    // Named exports
+    const namedExports = content.matchAll(/export\s+(?:async\s+)?(?:function|const|let|var|class)\s+(\w+)/g);
+    for (const match of namedExports) {
+      exports.push(match[1]);
+    }
+
+    // Export { ... }
+    const bracketExports = content.matchAll(/export\s*\{([^}]+)\}/g);
+    for (const match of bracketExports) {
+      const names = match[1].split(',').map(s => s.trim().split(/\s+as\s+/)[0].trim());
+      exports.push(...names);
+    }
+
+    return [...new Set(exports)];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Generate description from package info
+ */
+function generateDescription(pkg, hasCliCommands, exportedFunctions) {
+  let desc = pkg.description || `Provides ${pkg.name} functionality`;
+
+  // Ensure it ends with a period
+  if (!desc.endsWith('.')) desc += '.';
+
+  // Add "Use when" triggers based on keywords
+  const triggers = [];
+
+  if (pkg.keywords?.length) {
+    const keywordTriggers = pkg.keywords.slice(0, 3).map(k => `working with ${k}`);
+    triggers.push(...keywordTriggers);
+  }
+
+  if (hasCliCommands) {
+    triggers.push(`using the ${pkg.name} CLI`);
+  }
+
+  if (triggers.length) {
+    desc += ` Use when ${triggers.slice(0, 2).join(' or ')}.`;
+  }
+
+  // Truncate to 1024 chars
+  if (desc.length > 1024) {
+    desc = desc.slice(0, 1020) + '...';
+  }
+
+  return desc;
+}
+
+/**
+ * Generate SKILL.md content
+ */
+function generateSkillMd(pkg, options = {}) {
+  const { cliFlags = [], exports = [], readme = '' } = options;
+
+  const name = toKebabCase(pkg.name);
+  const description = generateDescription(pkg, cliFlags.length > 0, exports);
+
+  let content = `---
+name: ${name}
+description: ${description}
+---
+
+# ${pkg.name}
+
+`;
+
+  // When to Use
+  content += `## When to Use
+
+Invoke when you need to:
+`;
+
+  if (pkg.keywords?.length) {
+    pkg.keywords.slice(0, 4).forEach(kw => {
+      content += `- Work with ${kw}\n`;
+    });
+  } else {
+    content += `- Use ${pkg.name} functionality\n`;
+  }
+
+  content += '\n';
+
+  // Quick Start
+  content += `## Quick Start
+
+`;
+
+  if (pkg.bin) {
+    const binName = typeof pkg.bin === 'string' ? pkg.name : Object.keys(pkg.bin)[0];
+    content += `\`\`\`bash
+npx ${binName} --help
+\`\`\`
+
+`;
+  }
+
+  if (exports.length) {
+    content += `\`\`\`javascript
+import { ${exports.slice(0, 3).join(', ')} } from '${pkg.name}';
+\`\`\`
+
+`;
+  }
+
+  // CLI Reference
+  if (pkg.bin && cliFlags.length) {
+    content += `## CLI Reference
+
+\`\`\`
+npx ${Object.keys(pkg.bin)[0]} [options]
+\`\`\`
+
+**Options:**
+`;
+    cliFlags.slice(0, 10).forEach(flag => {
+      content += `- \`--${flag}\`\n`;
+    });
+    content += '\n';
+  }
+
+  // API Reference
+  if (exports.length) {
+    content += `## API Reference
+
+**Exported functions:**
+`;
+    exports.slice(0, 10).forEach(exp => {
+      content += `- \`${exp}\`\n`;
+    });
+    content += '\n';
+  }
+
+  // References
+  content += `## References
+
+`;
+  if (pkg.homepage) {
+    content += `- [Documentation](${pkg.homepage})\n`;
+  }
+  if (pkg.repository?.url) {
+    const repoUrl = pkg.repository.url.replace(/^git\+/, '').replace(/\.git$/, '');
+    content += `- [GitHub](${repoUrl})\n`;
+  }
+  content += `- [npm](https://www.npmjs.com/package/${pkg.name})\n`;
+
+  return content;
+}
+
+// Main
+async function main() {
+  console.log('skillify v0.0.1\n');
+
+  // Check if path exists
+  if (!fs.existsSync(targetPath)) {
+    console.error(`Error: Path not found: ${targetPath}`);
+    process.exit(1);
+  }
+
+  // Read package.json
+  const pkgPath = path.join(targetPath, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    console.error(`Error: No package.json found at ${targetPath}`);
+    process.exit(1);
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  console.log(`Package: ${pkg.name}@${pkg.version}`);
+
+  // Extract CLI info
+  let cliFlags = [];
+  if (pkg.bin) {
+    const binPath = typeof pkg.bin === 'string'
+      ? path.join(targetPath, pkg.bin)
+      : path.join(targetPath, Object.values(pkg.bin)[0]);
+
+    if (fs.existsSync(binPath)) {
+      cliFlags = extractCliInfo(binPath);
+      console.log(`CLI flags found: ${cliFlags.length}`);
+    }
+  }
+
+  // Extract exports
+  let exports = [];
+  const mainPath = path.join(targetPath, pkg.main || 'index.js');
+  if (fs.existsSync(mainPath)) {
+    exports = extractExports(mainPath);
+    console.log(`Exports found: ${exports.length}`);
+  }
+
+  // Read README
+  let readme = '';
+  const readmePath = path.join(targetPath, 'README.md');
+  if (fs.existsSync(readmePath)) {
+    readme = fs.readFileSync(readmePath, 'utf8');
+    console.log(`README.md: ${readme.length} chars`);
+  }
+
+  // Generate SKILL.md
+  const skillMd = generateSkillMd(pkg, { cliFlags, exports, readme });
+
+  if (dryRun || stdout) {
+    console.log('\n--- Generated SKILL.md ---\n');
+    console.log(skillMd);
+    if (dryRun) {
+      console.log('--- dry-run: not written ---');
+    }
+  } else {
+    const outPath = outputPath || path.join(targetPath, 'SKILL.md');
+    fs.writeFileSync(outPath, skillMd);
+    console.log(`\nWritten: ${outPath}`);
+  }
+}
+
+main().catch(err => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "skill-gen",
+  "version": "0.0.1",
+  "description": "Generate SKILL.md files for npm packages following Anthropic's Agent Skills specification",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "skill-gen": "./bin/skillify.js"
+  },
+  "keywords": [
+    "agent",
+    "skills",
+    "anthropic",
+    "claude",
+    "ai",
+    "documentation",
+    "npm"
+  ],
+  "author": "Melvin Carvalho",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/melvincarvalho/skillify"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}