diff --git a/src/main.rs b/src/main.rs
index 11cf1870..c60f1f09 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -48,13 +48,13 @@ enum Commands {
         #[command(subcommand)]
         cmd: SkillCommand,
         /// Root of the project (defaults to CWD)
-        #[arg(long)]
+        #[arg(short, long)]
         project_root: Option<PathBuf>,
     },
     /// Run diagnostic and health check
     Doctor {
         /// Project root (defaults to CWD)
-        #[arg(long)]
+        #[arg(short, long)]
         project_root: Option<PathBuf>,
     },
     /// Show status of managed symlinks
@@ -62,7 +62,7 @@ enum Commands {
         #[command(flatten)]
         args: StatusArgs,
         /// Project root (defaults to CWD)
-        #[arg(long)]
+        #[arg(short, long)]
         project_root: Option<PathBuf>,
     },
     /// Initialize a new agentsync configuration in the current or specified directory.
diff --git a/website/docs/src/content/docs/guides/skills.mdx b/website/docs/src/content/docs/guides/skills.mdx
index efdc2d30..02171cc4 100644
--- a/website/docs/src/content/docs/guides/skills.mdx
+++ b/website/docs/src/content/docs/guides/skills.mdx
@@ -91,7 +91,27 @@ Prompts and examples...
   - Examples: `weather-skill`, `my2-skill`, `a`.
   - Disallowed: uppercase letters, spaces, leading/trailing dashes, consecutive dashes (e.g., `bad--name`).
 
-- `version` is optional, but if present must be valid semver.
+- `version` is optional for installation, but **required** for the `skill update` command to work (must be valid semver).
+
+### Version requirement for updates
+
+When updating a skill with `agentsync skill update <SKILL_ID>`, the `SKILL.md` manifest **must** contain a valid `version` field in the frontmatter. Without it, the update will fail with the error "missing version in SKILL.md".
+
+Example with version:
+
+```md
+---
+name: my-skill
+version: 1.0.0
+description: A short description of this skill.
+---
+
+# Usage
+
+Prompts and examples...
+```
+
+If you don't intend to update a skill, the `version` field can be omitted from the manifest.
 
 If parsing fails, the CLI will return a validation error indicating the problem.
 
diff --git a/website/docs/src/content/docs/reference/cli.mdx b/website/docs/src/content/docs/reference/cli.mdx
index f583bea7..be113cb6 100644
--- a/website/docs/src/content/docs/reference/cli.mdx
+++ b/website/docs/src/content/docs/reference/cli.mdx
@@ -236,7 +236,7 @@ agentsync doctor [OPTIONS]
 ```
 
 **Options**:
-- `--project-root <PROJECT_ROOT>`: Project root (defaults to CWD).
+- `-p, --project-root <PROJECT_ROOT>`: Project root (defaults to CWD).
 
 **Diagnostics**:
 - Validates `agentsync.toml` existence and syntax.
@@ -277,7 +277,7 @@ agentsync status [--project-root <path>] [--json]
 ```
 
 **Flags**:
-- `--project-root <path>`: Optional. Path to the project root to locate the agentsync config. If omitted, the current working directory is used.
+- `-p, --project-root <path>`: Optional. Path to the project root to locate the agentsync config. If omitted, the current working directory is used.
 - `--json`: Output machine-readable JSON (pretty-printed) describing each managed target. Useful for CI.
 
 **Behavior**: