skillsets 0.8.0 → 0.9.0

package/dist/commands/audit.js

@@ -70,9 +70,18 @@ function isBinaryFile(filePath) {
         return false;
     }
 }
+/** Find the README_<NAME>.md file in content/ */
+function findReadme(cwd) {
+    const contentDir = join(cwd, 'content');
+    if (!existsSync(contentDir))
+        return null;
+    const entries = readdirSync(contentDir);
+    const readme = entries.find(f => /^README_[^/]+\.md$/i.test(f));
+    return readme ? join(contentDir, readme) : null;
+}
 function scanReadmeLinks(cwd) {
-    const readmePath = join(cwd, 'content', 'README.md');
-    if (!existsSync(readmePath))
+    const readmePath = findReadme(cwd);
+    if (!readmePath)
         return [];
     const relativeLinks = [];
     const content = readFileSync(readmePath, 'utf-8');
@@ -270,7 +279,7 @@ export async function audit(options = {}) {
     // 2. Required files
     spinner.text = 'Checking required files...';
     const hasContent = existsSync(join(cwd, 'content'));
-    const hasReadme = existsSync(join(cwd, 'content', 'README.md'));
+    const hasReadme = !!findReadme(cwd);
     const hasQuickstart = existsSync(join(cwd, 'content', 'QUICKSTART.md'));
     const hasInstallNotes = existsSync(join(cwd, 'content', 'INSTALL_NOTES.md'));
     const hasSkillsetYaml = existsSync(join(cwd, 'skillset.yaml'));
@@ -280,7 +289,7 @@ export async function audit(options = {}) {
     if (!hasContent)
         missingFiles.push('content/');
     if (!hasReadme)
-        missingFiles.push('content/README.md');
+        missingFiles.push('content/README_<NAME>.md');
     if (!hasQuickstart)
         missingFiles.push('content/QUICKSTART.md');
     if (!hasInstallNotes)

package/dist/commands/init.js

@@ -92,7 +92,7 @@ After installing via \`npx skillsets install {{AUTHOR_HANDLE}}/{{NAME}}\`, custo
 your-project/
 ├── .claude/          # Skills, agents, resources
 ├── CLAUDE.md         # Project config ← START HERE
-└── README.md         # Documentation
+└── README_{{NAME}}.md # Skillset documentation
 \`\`\`
 
 ---
@@ -356,7 +356,7 @@ export async function init(options) {
     }
     // Auto-detect existing files — core skillset files and primitives
     const coreFiles = [
-        'CLAUDE.md', 'README.md', 'QUICKSTART.md', 'INSTALL_NOTES.md',
+        'CLAUDE.md', 'QUICKSTART.md', 'INSTALL_NOTES.md',
         '.claude/', '.mcp.json',
     ];
     const detectedCore = coreFiles.filter((f) => {
@@ -416,13 +416,15 @@ export async function init(options) {
             .replace('{{PRODUCTION_URL}}', productionUrl)
             .replace('{{TAGS}}', tagsYaml);
         writeFileSync(join(cwd, 'skillset.yaml'), skillsetYaml);
-        // Generate content/README.md (if not copying existing)
-        if (!existsSync(join(cwd, 'content', 'README.md'))) {
+        // Generate content/README_<NAME>.md (if not copying existing)
+        // Named README avoids clobbering the user's own README.md on install
+        const readmeFilename = `README_${name.toUpperCase()}.md`;
+        if (!existsSync(join(cwd, 'content', readmeFilename))) {
             const readme = README_TEMPLATE
                 .replace(/\{\{NAME\}\}/g, name)
                 .replace(/\{\{DESCRIPTION\}\}/g, description)
                 .replace(/\{\{AUTHOR_HANDLE\}\}/g, authorHandle);
-            writeFileSync(join(cwd, 'content', 'README.md'), readme);
+            writeFileSync(join(cwd, 'content', readmeFilename), readme);
         }
         // Generate content/QUICKSTART.md (if not copying existing)
         if (!existsSync(join(cwd, 'content', 'QUICKSTART.md'))) {
@@ -442,7 +444,7 @@ export async function init(options) {
         console.log(chalk.green('\n✓ Initialized skillset submission:\n'));
         console.log('  skillset.yaml     - Manifest (edit as needed)');
         console.log('  content/          - Installable files');
-        console.log('    ├── README.md       - Documentation');
+        console.log(`    ├── ${readmeFilename} - Documentation`);
         console.log('    ├── QUICKSTART.md   - Post-install guide');
         console.log('    ├── INSTALL_NOTES.md - Pre-install notes');
         if (filesToCopy.length > 0) {

package/dist/commands/submit.js

@@ -234,7 +234,7 @@ Submitted via \`npx skillsets submit\`
 ### Checklist
 
 - [x] \`skillset.yaml\` validated against schema
-- [x] \`README.md\` with installation and usage instructions
+- [x] \`README_${skillset.name.toUpperCase()}.md\` with installation and usage instructions
 - [x] \`content/INSTALL_NOTES.md\` with install notes
 - [x] \`AUDIT_REPORT.md\` generated and passing
 - [x] \`content/\` directory with skillset files

package/dist/commands/view.js

@@ -14,7 +14,12 @@ export async function view(skillsetId) {
     }
     const [namespace, name] = skillsetId.split('/');
     const encodedPath = encodeURIComponent(namespace) + '/' + encodeURIComponent(name);
-    const readmeUrl = `${GITHUB_RAW_BASE}/skillsets/${encodedPath}/content/README.md`;
+    const readmeFile = metadata.files
+        ? Object.keys(metadata.files).find(f => /^content\/README_[^/]+\.md$/i.test(f))
+        : null;
+    const readmeUrl = readmeFile
+        ? `${GITHUB_RAW_BASE}/skillsets/${encodedPath}/${readmeFile}`
+        : `${GITHUB_RAW_BASE}/skillsets/${encodedPath}/content/README.md`;
     const auditUrl = `${GITHUB_RAW_BASE}/skillsets/${encodedPath}/AUDIT_REPORT.md`;
     const [readmeResponse, auditResponse] = await Promise.all([
         fetch(readmeUrl),

package/dist/lib/templates.d.ts

@@ -1,4 +1,4 @@
 export declare const SKILLSET_YAML_TEMPLATE = "schema_version: \"1.0\"\nbatch_id: \"{{BATCH_ID}}\"\n\n# Identity\nname: \"{{NAME}}\"\nversion: \"1.0.0\"\ndescription: \"{{DESCRIPTION}}\"\n\nauthor:\n  handle: \"{{AUTHOR_HANDLE}}\"\n  url: \"{{AUTHOR_URL}}\"\n\n# Verification\nverification:\n  production_links:\n    - url: \"{{PRODUCTION_URL}}\"\n  audit_report: \"./AUDIT_REPORT.md\"\n\n# Discovery\ntags:\n{{TAGS}}\n\ncompatibility:\n  claude_code_version: \">=1.0.0\"\n  languages:\n    - \"any\"\n\n# Lifecycle\nstatus: \"active\"\n\n# Content\nentry_point: \"./content/CLAUDE.md\"\n";
 export declare const README_TEMPLATE = "# {{NAME}}\n\n{{DESCRIPTION}}\n\n## Installation\n\n```bash\nnpx skillsets install {{AUTHOR_HANDLE}}/{{NAME}}\n```\n\n## Usage\n\n[Describe how to use your skillset]\n\n## What's Included\n\n[List the key files and their purposes]\n\n## License\n\n[Your license]\n";
-export declare const QUICKSTART_TEMPLATE = "# Quickstart\n\nAfter installing via `npx skillsets install {{AUTHOR_HANDLE}}/{{NAME}}`, customize the workflow for your project.\n\n---\n\n## What Was Installed\n\n```\nyour-project/\n\u251C\u2500\u2500 .claude/          # Skills, agents, resources\n\u251C\u2500\u2500 CLAUDE.md         # Project config \u2190 START HERE\n\u2514\u2500\u2500 README.md         # Documentation\n```\n\n---\n\n## Getting Started\n\n1. **Edit CLAUDE.md** \u2014 Replace placeholder content with your project's specifics\n2. **Customize .claude/** \u2014 Adapt skills, agents, and resources for your stack\n3. **Run** \u2014 `claude` to start using the skillset\n\n---\n\n## Customization Checklist\n\n- [ ] Update Identity & Constraints in CLAUDE.md\n- [ ] Configure style guides in .claude/resources/\n- [ ] Adapt agent definitions in .claude/agents/\n- [ ] Set up any required infrastructure (Docker, API keys, etc.)\n\n---\n\n## Resources\n\n[Add links to documentation, examples, or support channels]\n";
+export declare const QUICKSTART_TEMPLATE = "# Quickstart\n\nAfter installing via `npx skillsets install {{AUTHOR_HANDLE}}/{{NAME}}`, customize the workflow for your project.\n\n---\n\n## What Was Installed\n\n```\nyour-project/\n\u251C\u2500\u2500 .claude/          # Skills, agents, resources\n\u251C\u2500\u2500 CLAUDE.md         # Project config \u2190 START HERE\n\u2514\u2500\u2500 README_{{NAME}}.md # Skillset documentation\n```\n\n---\n\n## Getting Started\n\n1. **Edit CLAUDE.md** \u2014 Replace placeholder content with your project's specifics\n2. **Customize .claude/** \u2014 Adapt skills, agents, and resources for your stack\n3. **Run** \u2014 `claude` to start using the skillset\n\n---\n\n## Customization Checklist\n\n- [ ] Update Identity & Constraints in CLAUDE.md\n- [ ] Configure style guides in .claude/resources/\n- [ ] Adapt agent definitions in .claude/agents/\n- [ ] Set up any required infrastructure (Docker, API keys, etc.)\n\n---\n\n## Resources\n\n[Add links to documentation, examples, or support channels]\n";
 export declare const INSTALL_NOTES_TEMPLATE = "# {{NAME}}\n\n<!--\nInstall notes for pre-install display. Max 4000 characters total.\nWhat does this skillset do? What should users know before installing?\nThe dependency section below is populated by /audit-skill during review.\n-->\n\n## Dependencies\n\n<!-- Populated automatically by /audit-skill -->\n";

package/dist/lib/templates.js

@@ -65,7 +65,7 @@ After installing via \`npx skillsets install {{AUTHOR_HANDLE}}/{{NAME}}\`, custo
 your-project/
 ├── .claude/          # Skills, agents, resources
 ├── CLAUDE.md         # Project config ← START HERE
-└── README.md         # Documentation
+└── README_{{NAME}}.md # Skillset documentation
 \`\`\`
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillsets",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "CLI tool for discovering and installing verified skillsets",
   "type": "module",
   "bin": {