docs: Update exampels in README and help cmd

README.md

@@ -25,6 +25,35 @@ git pull  # Gets skilleton.json + skilleton.lock.json
 skilleton install  # Installs exact pinned versions
 ```
 
+## Skill input formats
+
+Skilleton supports several ways to specify skills:
+
+### Root repository skills
+For skills that live at the root of a repository:
+
+```bash
+skilleton add mhdcodes/react-query-skill
+# => repo: https://github.com/mhdcodes/react-query-skill, path: .
+```
+
+### Monorepo skills
+For skills inside a monorepo, make the subpath explicit:
+
+```bash
+# Three-segment shorthand
+skilleton add mindrally/skills/jest
+# => repo: https://github.com/mindrally/skills, path: jest
+
+# Longer paths in monorepos
+skilleton add owner/monorepo/path/to/skill
+# => repo: https://github.com/owner/monorepo, path: path/to/skill
+
+# Explicit URL form
+skilleton add https://github.com/owner/monorepo/path/to/skill
+# => repo: https://github.com/owner/monorepo, path: path/to/skill
+```
+
 > **Note**: Skilleton resolves skill refs via `git ls-remote` and requires a local git installation. It respects your local git credentials for private repositories.
 
 ## How it works
@@ -75,15 +104,15 @@ skilleton install                    # Reconcile lockfile with manifest, then in
 skilleton update                     # Refresh lockfile; reinstall only changed skills
 skilleton list [--format=table|json] # Show installed skills
 skilleton describe <skill>           # Inspect metadata, install tree, SKILL.md header
-skilleton validate                   # Check skill structure and security
+skilleton audit                      # Placeholder for future audit functionality
 ```
 
 ### Programmatic usage
 
 Skilleton can also be used from scripts via the package API:
 
 ```js
-const { createEnvironment, AddCommand, InstallCommand } = require('skilleton');
+import { createEnvironment, AddCommand, InstallCommand } from 'skilleton';
 
 async function run() {
   const env = createEnvironment(process.cwd());

bin/skilleton.ts

@@ -32,7 +32,8 @@ function parseArgs(argv: string[]): { command: string | null; args: CommandArgs
   for (let i = 0; i < rest.length; i += 1) {
     const token = rest[i];
     if (token.startsWith('--')) {
-      const [flag, value] = token.slice(2).split('=');
+      const [rawFlag, value] = token.slice(2).split('=');
+      const flag = rawFlag === 'h' ? 'help' : rawFlag;
       if (value !== undefined) {
         flags[flag] = value;
         continue;
@@ -45,6 +46,10 @@ function parseArgs(argv: string[]): { command: string | null; args: CommandArgs
       } else {
         flags[flag] = true;
       }
+    } else if (token.startsWith('-') && token.length > 1) {
+      const rawFlag = token.slice(1);
+      const flag = rawFlag === 'h' ? 'help' : rawFlag;
+      flags[flag] = true;
     } else {
       positional.push(token);
     }
@@ -53,9 +58,16 @@ function parseArgs(argv: string[]): { command: string | null; args: CommandArgs
   return { command, args: { positional, flags } };
 }
 
-function printHelp(): void {
+function printHelp(command?: string): void {
+  if (command === 'add') {
+    console.log(
+      `Add a skill to your project\n\nUsage:\n  skilleton add <owner/skill[@ref]>\n\nArguments:\n  <owner/skill[@ref]>    Skill identifier (required)\n\nExamples:\n  # Add from monorepo\n  skilleton add mindrally/skills/jest\n\n  # Add from root repository\n  skilleton add mhdcodes/react-query-skill\n\n  # Add specific ref\n  skilleton add mindrally/skills/jest@main\n\n  # Add with explicit URL\n  skilleton add https://github.com/owner/repo/path/to/skill\n\nThis command:\n  1. Parses the skill identifier\n  2. Adds the skill to skilleton.json\n  3. Runs 'skilleton install' to fetch and lock the skill\n`,
+    );
+    return;
+  }
+
   console.log(
-    `Skilleton — Skills Skeleton\n\nUsage:\n  skilleton <command> [options]\n\nCommands:\n  add <owner/skill[@ref]>     Add a skill to skilleton.json\n  install [--agent <name>]    Install skills defined in skilleton.json\n  update [--agent <name>]     Refresh lockfile and reinstall changed skills\n  list                        Show declared skills and pinned commits\n  describe <skill-name>       Inspect a skill's metadata and installed contents\n  audit                       Placeholder for future audit functionality\n\nRun "skilleton <command> --help" for details.\n`,
+    `Skilleton — Skills Skeleton\n\nUsage:\n  skilleton <command> [options]\n\nCommands:\n  add <owner/skill[@ref]>     Add a skill to skilleton.json\n  install [--agent <name>]    Install skills defined in skilleton.json\n  update [--agent <name>]     Refresh lockfile and reinstall changed skills\n  list [--format=table|json] Show declared skills and pinned commits\n  describe <skill-name>       Inspect a skill's metadata and installed contents\n  audit                       Placeholder for future audit functionality\n\nRun "skilleton <command> --help" for details.\n`,
   );
 }
 
@@ -68,6 +80,12 @@ async function main(): Promise<void> {
     return;
   }
 
+  // Handle individual command help
+  if (args.flags.help) {
+    printHelp(command);
+    return;
+  }
+
   const handler = commands[command];
   if (!handler) {
     console.error(`Unknown command: ${command}`);