docs: Simplify REAMDE

Author: Fcmam5

README.md

@@ -1,121 +1,92 @@
 # Skilleton
 
-**Skilleton** is a skills skeleton — a lightweight CLI that treats AI skills like deterministic project dependencies. Think `package.json`, `vscode/extensions.json`, or other project-scoped manifests—except the entries point to versioned `SKILL.md` folders that can be shared, reviewed, and upgraded with confidence. Vercel's `skills.sh` inspired parts of the DX, but Skilleton differentiates itself with project-first manifests and strict version locking.
+**Deterministic AI skill dependency management for teams**
 
-## Why "Skilleton"?
+Manage AI skills like npm packages - with project manifests, lockfiles, and reproducible installations.
 
-The name "Skilleton" comes from **"skills skeleton"** — it provides the structural framework for managing AI skill dependencies in your projects. Everyone else was already using "[skillset](https://www.npmjs.com/package/skillset)", "[skillsets](https://www.npmjs.com/package/skillsets)", "[Skillful](https://www.npmjs.com/package/skillful)", and similar names, so we went with something that captures the essence: a minimal, skeletal structure that holds your skills together.
+## Why this exists
 
-## Installation
+`skills.sh` is great for installing skills globally, but teams need:
 
-```bash
-npm install -g skilleton
-```
+- **Reproducible environments** - Everyone gets the same skill versions
+- **Project-scoped dependencies** - Skills live with your code, not globally  
+- **Version locking** - No surprises from upstream changes
+- **Team collaboration** - Commit manifests to version control
 
-Or using npx:
+## Quickstart
 
 ```bash
-npx skilleton --help
-```
+# Add a skill to your project
+skilleton add Mindrally/skills/jest
 
-## Usage
-
-
-### Adding Skills
-
-In your project, run:
+# Install all skills (like npm install)
+skilleton install
 
-```bash
-skilleton add <owner/skill[@ref]>
+# Team member gets exact same versions
+git pull  # Gets skilleton.json + skilleton.lock.json
+skilleton install  # Installs exact pinned versions
 ```
 
-For example:
-
-```bash
-skilleton add Mindrally/skills/chrome-extension-development@47f47c1
-
-# or
-skilleton add Mindrally/skills/chrome-extension-development # defaults to latest commit on main
+## How it works
+
+**skilleton.json** (commit this):
+```json
+{
+  "skills": [
+    {
+      "name": "jest", 
+      "repo": "Mindrally/skills",
+      "path": "jest",
+      "ref": "47f47c1"
+    }
+  ]
+}
 ```
 
-This will create a `skilleton.json` file in your project root, update `skilleton.lock.json`, and immediately install the requested skill (and the rest of the manifest) into `~/.skilleton/skills`, using `~/.skilleton/cache` for repo reuse.
-
-Think of it like running `npm install --save`: the manifest is updated and the dependency is fetched in one step.
-
-> [!IMPORTANT]
-> Make sure to commit your `skilleton.json` and `skilleton.lock.json` files to version control, and add `~/.skilleton` to your `.gitignore` file.
-
-
-### Installing Skills
-
-If you have a `skilleton.json` file in your project (and you should :smirk:), you can install the skills by running:
-
-```bash
-skilleton install
+**skilleton.lock.json** (commit this):
+```json
+{
+  "skills": {
+    "jest": {
+      "name": "jest",
+      "repo": "Mindrally/skills", 
+      "path": "jest",
+      "ref": "47f47c1",
+      "commit": "abc123def456...",
+      "timestamp": "2025-01-01T00:00:00Z"
+    }
+  }
+}
 ```
 
-### Listing Skills
+## Commands
 
 ```bash
-skilleton list
+skilleton add <owner/skill[@ref]>    # Add skill and update manifest
+skilleton install                    # Install exact versions from lockfile  
+skilleton update                     # Refresh lockfile and reinstall
+skilleton list                       # Show installed skills
 ```
 
-### Updating Skills
-
-```bash
-skilleton update
-```
-
-## Features
-
-- Declarative `skilleton.json` manifest that lives alongside your other project configs
-- Lockfile-driven installs (`skilleton.lock.json`) for deterministic, versioned skills
-- Git-based resolution today (GitHub-first for now, but architecture keeps future sources open)
-- Cache-friendly git operations stored in `~/.skilleton/cache`
-- Commands: `add`, `install`, `update`, `list`, `audit`
-
-## Development
-
-### Prerequisites
+## vs skills.sh
 
-- Node.js 24.x (see [.nvmrc](.nvmrc))
+| Feature | Skilleton | skills.sh |
+|---------|-----------|-----------|
+| Team collaboration | ✅ Manifests + lockfiles | ❌ Global only |
+| Reproducible builds | ✅ Exact commit pinning | ❌ Latest by default |
+| Project isolation | ✅ Per-project skills | ❌ Shared global |
+| Version control | ✅ Git-friendly | ❌ Not designed for it |
 
-### Installation
+## Installation
 
 ```bash
-npm install
-npm run build
-node dist/bin/skilleton.js --help
+npm install -g skilleton
 ```
 
-## Repository Norms
-
-- Discuss ideas in GitHub issues before contributing
-- Small, focused pull requests only
-- Human-reviewed contributions; automated/AI-only PRs will be closed
-- MIT license, no telemetry, privacy-first design
+## Privacy
 
-## Documentation
-
-- [docs/architecture.md](docs/architecture.md)
-- [docs/usage.md](docs/usage.md)
-- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
-- [CONTRIBUTING.md](CONTRIBUTING.md)
-- [SECURITY.md](SECURITY.md)
-- [PRIVACY.md](PRIVACY.md)
+No telemetry, no phone home. Skills are cached locally, manifests are yours to control.
 
 ## License
 
-This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
-
-## Acknowledgments
-
-- Vercel's `skills.sh` CLI for inspiring parts of the developer experience
-- Brian and Giuseppe for working on a similar idea for a different context/purpose
-
-## Support
-
-If you find this project helpful and want to support its development, you can:
-
-- **Ko-fi**: [ko-fi.com/fcmam5](https://ko-fi.com/fcmam5)
-- **Buy Me a Coffee**: [buymeacoffee.com/ngcmbf6](https://buymeacoffee.com/ngcmbf6)
+MIT - see [LICENSE](LICENSE)

ROADMAP.md

@@ -17,10 +17,14 @@ A living document outlining the near-term milestones for the Skilleton CLI.
 
 ## v0.2 "Safety Net"
 
-1. **`skilleton audit` command (scaffolding exists)**
+1. **`skilleton validate` command**
+   - Validate skill structure and required files
+   - Check for common security issues in SKILL.md
+   - Verify repository accessibility and permissions
+2. **`skilleton audit` command (scaffolding exists)**
    - Scan installed `SKILL.md` files for prompt-injection red flags (e.g., self-modifying instructions, network exfiltration hints).
    - Emit structured findings so CI can fail on high-risk issues.
-2. **Agent-aware linking**
+3. **Agent-aware linking**
    - Allow per-agent overrides in manifest (`preferredAgent`).
    - Offer `skilleton install --agent <name>` to switch symlink targets without reinstalling.
 

package.json

@@ -4,6 +4,14 @@
   "description": "Skills skeleton: deterministic AI skill dependency manager",
   "type": "commonjs",
   "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Fcmam5/skilleton"
+  },
+  "homepage": "https://github.com/Fcmam5/skilleton#readme",
+  "bugs": {
+    "url": "https://github.com/Fcmam5/skilleton/issues"
+  },
   "bin": {
     "skilleton": "dist/bin/skilleton.js"
   },