@maccesar/aiskills 1.19.0 → 1.20.0

package/README.md

@@ -540,10 +540,11 @@ How to invoke it — in whatever words you'd use anyway:
 
 ### aiskills list
 
-Lists all available skills with their descriptions.
+Lists all available skills with their descriptions, marking each one installed (✓) or not (✗). It works before you have installed anything — descriptions for a skill that is not installed come from the copy bundled in this package — so the list doubles as the catalog of what is on offer.
 
 ```bash
 aiskills list
+aiskills ls    # same thing
 ```
 
 ---

package/bin/aiskills.js

@@ -25,6 +25,7 @@ program
 // List command
 program
   .command('list')
+  .alias('ls')
   .description('List available AI skills')
   .action(listCommand);
 

package/lib/commands/list.js

@@ -111,25 +111,44 @@ export function parseDescription(frontmatter) {
 }
 
 /**
- * Read a skill's description from disk.
- * @param {string} skillDir - Directory holding the skill's SKILL.md
- * @returns {{description: string|null, installed: boolean}}
+ * Read a description out of one SKILL.md.
+ * @param {string} skillMd - Path to a SKILL.md
+ * @returns {string|null} The first sentence, or null when unreadable
  */
-function readSkillMetadata(skillDir) {
-  const skillMd = join(skillDir, 'SKILL.md');
-  if (!existsSync(skillMd)) {
-    return { description: null, installed: false };
-  }
-
+function readDescription(skillMd) {
   try {
     const content = readFileSync(skillMd, 'utf8');
     const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!frontmatter) return { description: null, installed: true };
-
-    return { description: parseDescription(frontmatter[1]), installed: true };
+    if (!frontmatter) return null;
+    return parseDescription(frontmatter[1]);
   } catch {
-    return { description: null, installed: true };
+    return null;
+  }
+}
+
+/**
+ * Read a skill's description, preferring the installed copy and falling back
+ * to the one bundled in this package.
+ *
+ * The fallback is what lets the list describe a skill that is not installed
+ * yet — which is exactly when someone runs `aiskills list` and needs to know
+ * what they would be installing. `skills/` ships in the npm tarball, so the
+ * bundled copy is there for every install channel.
+ * @param {string} skillDir - Where the skill would be installed
+ * @param {string} name - Skill name, used to find the bundled copy
+ * @returns {{description: string|null, installed: boolean}}
+ */
+function readSkillMetadata(skillDir, name) {
+  const installedMd = join(skillDir, 'SKILL.md');
+  if (existsSync(installedMd)) {
+    return { description: readDescription(installedMd), installed: true };
   }
+
+  const bundledMd = new URL(`../../skills/${name}/SKILL.md`, import.meta.url);
+  return {
+    description: existsSync(bundledMd) ? readDescription(bundledMd) : null,
+    installed: false,
+  };
 }
 
 export async function listCommand() {
@@ -139,21 +158,13 @@ export async function listCommand() {
 
   const skillsDir = getAgentsSkillsDir();
 
-  if (!existsSync(skillsDir)) {
-    console.log(chalk.yellow('No skills installed yet.'));
-    console.log('Install with:');
-    console.log(chalk.cyan('  aiskills install'));
-    console.log('');
-    return;
-  }
-
   const rows = [];
   let installedCount = 0;
   let maxNameLen = 0;
 
   for (const name of SKILLS) {
     const skillDir = join(skillsDir, name);
-    const { description, installed } = readSkillMetadata(skillDir);
+    const { description, installed } = readSkillMetadata(skillDir, name);
 
     if (installed) installedCount++;
     if (name.length > maxNameLen) maxNameLen = name.length;
@@ -179,6 +190,18 @@ export async function listCommand() {
   }
 
   console.log('');
+
+  if (installedCount === 0) {
+    // Naming the directory would point at somewhere that does not exist yet.
+    console.log(chalk.gray(`0/${SKILLS.length} installed`));
+    console.log('');
+    console.log(chalk.yellow('No skills installed yet.'));
+    console.log('Install with:');
+    console.log(chalk.cyan('  aiskills install'));
+    console.log('');
+    return;
+  }
+
   console.log(chalk.gray(`${installedCount}/${SKILLS.length} installed at ${skillsDir}`));
   console.log('');
   console.log(chalk.gray('Run `aiskills status` for installation health.'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {