agent-skill-factory 1.2.1__tar.gz

agent_skill_factory-1.2.1/CHANGELOG.md

@@ -0,0 +1,178 @@
+# Changelog
+
+All notable changes to Skill Factory will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.2.1] - 2026-10-20
+
+### Changed
+
+- **PyPI Distribution Package Renamed**: Updated distribution package name in `pyproject.toml` to `agent-skill-factory` to avoid PyPI namespace similarity collisions with legacy packages.
+- **Python Import & CLI Preserved**: The Python runtime import package remains `skillfactory` and both existing CLI commands (`skillfactory` and `skill-factory`) remain unchanged.
+- **PyPI OIDC Publishing**: Updated workflow `.github/workflows/pypi-publish.yml` environment target URL to `https://pypi.org/p/agent-skill-factory`.
+- **Documentation Updates**: Updated `README.md` and quickstart guides with `pip install agent-skill-factory`.
+
+---
+
+## [1.2.0] - 2026-10-20
+
+### Added
+
+- **PyPI Distribution Readiness (Workstream A)**:
+  - Packaging configuration verified in `pyproject.toml` with dual console scripts: `skillfactory` and `skill-factory`.
+  - Comprehensive bundled package data rules ensuring `data/*/*.json` and subdirectories are fully included in wheels.
+  - PyPI namespace collision audit documented; publication pathway configured via GitHub Actions OIDC Trusted Publishing (`.github/workflows/pypi-publish.yml`).
+  - Isolated clean-environment installation testing verified outside source tree.
+- **Beginner Onboarding & Guided UX (Workstream B)**:
+  - Interactive step-by-step onboarding wizard (`skillfactory guide`) covering diagnostic pre-flight, assistant selection, specification, generation, and optional installation.
+  - Enhanced top-level interactive menu with choices 0–12 and zero required flags.
+- **Curated Domain Skill Packs (Workstream D)**:
+  - 3-tier domain taxonomy schema (Personal, Professional, Developer) covering 31 domain specializations.
+  - 5 curated domain packs (`office-productivity`, `finance-erp`, `hr-workforce`, `project-management`, `developer-security`) defined in `skillfactory/data/packs.json`.
+  - Full pack lifecycle CLI manager (`skillfactory pack list`, `install`, `verify`, `uninstall`) with atomic rollback on partial batch failures.
+  - 9 new production-grade reference skills (total 14 skills in library), all achieving Grade A (≥90/100) on the quality rubric.
+- **Optional AI-Assisted Skill Creation (Workstream E)**:
+  - Provider-neutral AI creation engine (`skillfactory ai-create`) supporting local Ollama, OpenAI-compatible APIs, and offline deterministic mock providers.
+  - Pre-execution AST safety quarantine scanning for dangerous calls before running tests.
+  - Isolated subprocess execution sandbox (10.0s timeout) with bounded self-repair loop (up to 3 retries).
+- **Multi-Agent Platform Expansion (Workstream F)**:
+  - Expanded compatibility to 8 AI coding assistants: Claude Code, Google Antigravity, Cursor, OpenAI Codex, Windsurf, Continue, Cline, and GitHub Copilot.
+  - Added native detection rules, directory schemas, and shorthand alias normalization (`windsurf`, `codeium`, `continue`, `cline`, `copilot`, `github-copilot`).
+- **Security & Quality Hardening (Workstream G)**:
+  - Symlink escape defense in file installer and package importer preventing access to files outside skill directory.
+  - 3 new prompt injection rules (`INJ005` system prompt extraction, `INJ006` webhook exfiltration, `INJ007` adversarial roleplay).
+  - Multiagent validation suite expanded to test all 8 platforms through 6-stage lifecycle (`install`, `validate`, `execute`, `update`, `rollback`, `uninstall`).
+- **Natural-Language Requirements & Behavioral Testing (Phase 16)**:
+  - Natural-language requirement parser (`skillfactory/ai/requirements.py`) extracting intent, constraints, inputs/outputs, and generating an automated assumption register.
+  - Automated behavioral unit test generation (`skillfactory/ai/test_gen.py`) establishing traceability matrices mapped directly to user acceptance criteria.
+  - Deterministic non-AI fallback synthesis engine and bounded self-repair loop with automated code modification diffing.
+- **Skill Library, Multi-Attribute Discovery & Community Quarantine (Phase 17)**:
+  - 3-tier domain taxonomy and multi-attribute catalog search filtering by tags, author, platform, and minimum quality score.
+  - Pack installation preview CLI with target filesystem inspection and destination collision detection.
+  - Community submission quarantine gate with pre-execution AST screening and manifest integrity verification.
+- **Production Hardening & 16-Vector Threat Model (Phase 18)**:
+  - Comprehensive 16-vector security audit (`docs/final-development/securityFindings.md`) covering Zip-Slip, symlink escapes, AST dangerous calls, secrets, prompt injection, and host isolation.
+  - Multiagent validation suite expanded to 8 platforms across all 6 lifecycle stages (`install`, `validate`, `execute`, `update`, `rollback`, `uninstall`).
+  - Production benchmark harness confirming sub-10ms CLI launch and high-throughput AST scanning.
+- **Markdown Quality & CI Regression Suite**:
+  - Full remediation of 179 Markdown formatting violations across all 152 repository documentation files and skills.
+  - Template engine updates ensuring zero blank-line or heading violations (MD022, MD031, MD032, MD040, MD058, MD060).
+  - Automated CI regression test suite (`tests/test_markdown_lint.py`) integrated into GitHub Actions across Ubuntu, macOS, and Windows.
+- **Community & Launch Kit (Workstreams C & H)**:
+  - Community launch preparation kit with platform-tailored announcements for Hacker News, Reddit, and LinkedIn.
+  - GitHub issue forms (`bug_report.yml`, `feature_request.yml`) and pull request template (`pull_request_template.md`).
+  - Zero-telemetry adoption measurement policy.
+
+---
+
+## [1.1.0] - 2026-10-19
+
+### Added
+
+- **Public Launch & Developer Adoption (Phase 11)**:
+  - Comprehensive, honest `README.md` with explicit product boundaries and verified platform support tiers.
+  - Beginner-friendly platform-specific onboarding guide (`docs/beginnerQuickstart.md`) for macOS, Windows, and Linux.
+  - 5 reproducible, real-world reference skill demonstrations with automated validation harness (`scripts/run_demos.py` and `docs/demonstrations.md`).
+  - Community launch preparation kit (`docs/launchPreparation.md`) including Show HN/Reddit drafts, FAQ, and AI coding assistant comparisons.
+- **Beginner-Friendly Experience (Phase 12)**:
+  - Pre-flight diagnostic engine (`skillfactory doctor --guided`) checking Python runtime, permissions, shell PATH, and assistant installations with concrete remediation commands.
+  - Intuitive positional skill name CLI syntax (`skillfactory new my-skill`) with automatic trigger guidance.
+  - Interactive questionnaire (`skillfactory interview`) enhancements with live kebab-case sanitization loops and target assistant prompts.
+  - Universal 3-part structured error formatting (`What happened`, `Why it happened`, `What to do next`) across all CLI errors with stack trace suppression.
+  - Automated usability regression test suite (`tests/test_beginner_experience.py`).
+- **Skill Library & Community Ecosystem (Phase 13)**:
+  - Built-in offline reference catalog (`skillfactory/data/catalog.json`) containing 5 Grade-A reference skills with instant (<10ms) local search.
+  - Static prompt injection and adversarial instruction scanner rules (`INJ001`–`INJ004` in `skillfactory/scanner.py`) detecting directive overrides, persona shifts, remote execution pipelines, and hidden markup.
+  - Objective 100-point community quality scoring rubric (`docs/skillQualityStandards.md`) defining evaluation criteria for Grade A/B/C/F classifications.
+  - Standardized community contribution workflow (`docs/communityContributions.md`) and GitHub submission issue form (`.github/ISSUE_TEMPLATE/skill_submission.yml`).
+  - Untrusted archive import quarantine warning banners in `skillfactory import`.
+- **Production Hardening & Ecosystem Expansion (Phase 14)**:
+  - Cross-platform regression test suite (`tests/test_hardening.py`) verifying deep Unicode paths, spaces, Windows reserved device names (`CON`, `PRN`, `NUL`), Zip Slip traversal defenses, and atomic rollbacks.
+  - Repeatable performance benchmark harness (`scripts/run_benchmarks.py`) profiling cold starts, scaffolding throughput, AST scanning rate, and manifest verification.
+  - Comprehensive 14-vector security threat model audit (`docs/securityThreatModel.md`).
+  - Rigorous 4-tier platform compatibility matrix (`docs/compatibilityMatrix.md`) distinguishing verified autonomous activation, manual invocation, directory discovery, and simulated testing.
+  - Ecosystem expansion assessment (`docs/ecosystemExpansion.md`) evaluating Windsurf, Continue.dev, Cline, and Copilot.
+
+---
+
+## [1.0.1] - 2026-10-19
+
+### Fixed
+
+- **Platform Shorthand Aliases (DEF-04)**:
+  - Enabled intuitive CLI shorthand aliases (`claude`, `anthropic`, `openai`, `google`, `agy`) for `--platform` across `install`, `update`, `rollback`, `uninstall`, and `install-self`.
+- **Bytecode & Cache Manifest Filtering (DEF-05)**:
+  - Filtered Python bytecode (`__pycache__`, `*.pyc`) and OS cache files (`.DS_Store`, `Thumbs.db`) from `create_manifest` and `verify_manifest` to prevent false positive integrity discrepancies when tests run before installation.
+
+### Added
+
+- **Phase 10 Automated Validation Suites**:
+  - `tests/run_multiagent_validation.py`: Automated multi-agent lifecycle testing across Claude Code, Cursor, Codex, and Antigravity.
+  - `tests/run_security_validation.py`: Comprehensive adversarial security and host isolation validation.
+  - 4 new unit regression tests expanding the test suite to 114 tests with 100% pass rate.
+
+---
+
+## [1.0.0] - 2026-10-19
+
+### Added
+
+- **Core Generator Engine (Phase 1)**:
+  - Atomic directory generation with sibling staging (`.tmp-*`) and rollback protection.
+  - Safe YAML frontmatter serializer preventing parsing errors on colons, quotes, and hashes (resolves `DEF-01`).
+  - Windows reserved name (`CON`, `PRN`, `AUX`, `NUL`) and platform reserved name protection (resolves `DEF-02`).
+  - Cryptographic file manifest (`.skillfactory/manifest.json`) recording SHA-256 hashes for all generated files.
+  - Legacy backward-compatible wrapper script `scripts/create_skill.py`.
+- **Natural Language Skill Builder & Offline Interview (Phase 2)**:
+  - Root `SKILL.md` orchestrating Host-AI assistant interactions across Claude Code, Cursor, Codex, and Antigravity.
+  - Interactive terminal questionnaire CLI (`skillfactory interview`).
+  - Batch answers automation mode (`--answers`).
+  - Intelligent keyword heuristic router recommending the optimal template family.
+  - 5 reusable starter template families: `python-script`, `file-transform`, `checklist-review`, `workflow-runbook`, `instructions-only`.
+  - Deterministic golden byte-for-byte reproducibility tests.
+- **Multi-Agent Compatibility & Platform Adapters (Phase 3)**:
+  - Data-driven platform database `skillfactory/data/platforms.json` covering Claude Code, Cursor, OpenAI Codex, and Google Antigravity.
+  - Environment detector identifying active AI coding tools and configurations.
+  - System diagnostics tool `skillfactory doctor` verifying discovery paths.
+  - Shared-folder collision resolver preventing duplicate entries in `.agents/skills/`.
+- **Easy Installation & Automatic Backups (Phase 4)**:
+  - Local installation registry tracking installed skills across project and user scopes.
+  - Allow-list safe copy installer with optional symlink (`--link`) support.
+  - Safe updating (`skillfactory update`) with automated backup snapshots preserved in `.skillfactory/backups/`.
+  - Single-command rollback mechanism (`skillfactory rollback`) restoring previous working snapshots.
+  - Non-destructive uninstall (`skillfactory uninstall`) preserving user-modified assets.
+  - Self-installation command (`skillfactory install-self`) equipping host AI agents with Skill Factory.
+- **Skill Testing & Quality Evaluation (Phase 5)**:
+  - Isolated subprocess test runner (`skillfactory test`) with strict 10.0s execution timeout and environment sandboxing.
+  - Python AST safety scanner detecting `eval()`, `exec()`, `__import__()`, `os.system()`, and destructive commands without execution.
+  - Objective 0–100 quality scoring engine (`skillfactory eval`) assessing Structure, Portability, Documentation, Tests, and Safety.
+  - Automated report persistence to `.skillfactory/test-results.json` and `.skillfactory/evaluation.json`.
+- **Skill Library & Secure Packaging (Phase 6)**:
+  - Local catalog indexer and sub-millisecond offline search (`skillfactory search`).
+  - Reproducible ZIP export (`skillfactory export`) with SHA-256 checksum sidecars.
+  - Secure ZIP import (`skillfactory import`) with strict defense against "Zip-Slip" path traversal exploits.
+  - Standalone GitHub repository scaffolding generator (`skillfactory publish`).
+  - 5 curated, Grade-A reference skills shipped in `examples/`: `pdf-to-markdown`, `docker-security-audit`, `git-release-helper`, `sql-migration-linter`, `api-schema-validator`.
+- **Beginner Experience & Accessibility (Phase 7)**:
+  - Interactive numbered top menu (`skillfactory menu` or invocation without args in interactive terminal).
+  - 3-part beginner-friendly error messages (What happened, Why, Next steps) eliminating raw Python stack traces.
+  - Complete, tested OS Quickstart guides for macOS, Windows, and Linux in `docs/quickstart/`.
+  - Strict compliance with `NO_COLOR` standard and complete removal of color-only semantic signals.
+  - Comprehensive Beginner's Glossary covering 17 core concepts in `docs/glossary.md`.
+- **Security & Reliability Hardening (Phase 8)**:
+  - Credential and secret scanner detecting AWS keys, GitHub PATs, OpenAI keys, and private certificates before publish.
+  - Cross-platform path resilience across spaces, non-ASCII characters, and deep directories.
+  - Robust parser fuzzing suite handling truncated YAML, null bytes, and malformed JSON cleanly.
+  - GitHub Actions supply-chain pinning to full 40-character commit hashes.
+  - Formal `SECURITY.md` vulnerability reporting policy and SLA.
+  - Multi-OS CI testing matrix across Ubuntu, macOS, and Windows on Python 3.9, 3.11, and 3.13.
+
+### Fixed
+
+- `DEF-01`: Safe YAML frontmatter serializer prevents crashes from colons, hashes, and quotes in descriptions.
+- `DEF-02`: Generator and validator strictly reject Windows reserved device names and platform reserved directory names.
+- `DEF-03`: Minimum supported Python version validated as 3.9+ across macOS, Windows, and Linux.

agent_skill_factory-1.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skill Factory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_skill_factory-1.2.1/MANIFEST.in

@@ -0,0 +1,5 @@
+recursive-include skillfactory/templates *.tmpl
+recursive-include skillfactory/data *.json
+include LICENSE
+include README.md
+include CHANGELOG.md

agent_skill_factory-1.2.1/PKG-INFO

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: agent-skill-factory
+Version: 1.2.1
+Summary: Free, open-source Agent Skills generation and management for Claude Code, Cursor, Codex, Antigravity, Windsurf, Continue, Cline, and Copilot.
+Author: Skill Factory Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/imnashraf/skill-factory
+Project-URL: Repository, https://github.com/imnashraf/skill-factory.git
+Project-URL: Documentation, https://github.com/imnashraf/skill-factory/tree/main/docs
+Project-URL: Issues, https://github.com/imnashraf/skill-factory/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Skill Factory
+
+[![Tests](https://img.shields.io/badge/tests-100%25%20passing-brightgreen.svg)](.github/workflows/tests.yml)
+[![Python](https://img.shields.io/badge/python-3.9%20%7C%203.11%20%7C%203.13-blue.svg)](pyproject.toml)
+[![Dependencies](https://img.shields.io/badge/dependencies-0%20(standard%20library)-success.svg)](skillfactory/)
+[![License](https://img.shields.io/badge/license-MIT-purple.svg)](LICENSE)
+[![Specification](https://img.shields.io/badge/spec-agentskills.io-orange.svg)](https://agentskills.io/specification)
+
+**Skill Factory** is an open-source, local-first generator, validator, evaluator, package manager, and lifecycle system for **Agent Skills** conforming to the [Agent Skills open specification](https://agentskills.io/specification).
+
+It bridges the gap between conversational AI prompts and production-grade tools across 8 major AI coding assistants—including **Claude Code**, **Google Antigravity**, **Cursor**, **OpenAI Codex**, **Windsurf**, **Continue**, **Cline**, and **GitHub Copilot**.
+
+```text
+   ┌───────────────────────────────────────────────────────────────┐
+   │                       SKILL FACTORY                           │
+   │                                                               │
+   │  [1] Create a new skill (interactive interview)               │
+   │  [2] Search local skill library                               │
+   │  [3] Validate an existing skill folder                        │
+   │  [4] Run skill automated tests                                │
+   │  [5] Evaluate skill quality score (0–100)                     │
+   │  [6] Scan skill for secrets and safety issues                 │
+   │  [7] Platform health doctor (check AI agents)                 │
+   │  [8] Install a skill into an AI tool                          │
+   │  [9] List installed skills                                    │
+   │  [10] Beginner guided walkthrough (step-by-step wizard)       │
+   │  [11] AI-assisted skill creation (natural language)           │
+   │  [12] Curated domain skill packs (browse & install)           │
+   │  [0] Exit                                                     │
+   │                                                               │
+   │  100% Python Standard Library • Zero Paid APIs • Local-First  │
+   └───────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## What Skill Factory Does & Does Not Do
+
+To ensure complete transparency and prevent adoption friction, here are the explicit design boundaries of Skill Factory:
+
+### What Skill Factory Does
+
+- ✅ **Scaffolds Specification-Compliant Skills:** Creates standardized folders with validated YAML frontmatter (`name`, `description`), structured markdown instructions (`SKILL.md`), human documentation (`README.md`), unit tests (`tests/`), scripts (`scripts/`), and cryptographic SHA-256 manifests (`.skillfactory/manifest.json`).
+- ✅ **Evaluates & Scores Quality (0–100):** Grades skills objectively against 5 dimensions: specification compliance, portability, progressive disclosure, test execution, and code safety.
+- ✅ **Scans for Security Risks & Injections:** Static AST scanner flags dangerous calls (`eval`, `exec`, `os.system`, shell injection). Secrets scanner flags leaked AWS keys, GitHub tokens, and OpenAI/Anthropic keys. Hardened with 7 categories of prompt injection detection and symlink escape defense.
+- ✅ **Manages Complete Lifecycles:** Installs skills into official AI agent directories, creates automatic timestamped backup snapshots before updates, performs single-command rollbacks, and cleanly uninstalls skills while preserving user data.
+- ✅ **Curated Domain Skill Packs:** Ships with 5 curated domain packs (Office Productivity, Finance & ERP, HR & Workforce, Project Management, Developer & Security) containing 14 reference skills scoring Grade A (≥90/100).
+- ✅ **Optional AI-Assisted Skill Creation:** Pluggable, provider-neutral synthesis engine (`skillfactory ai-create`) supporting local Ollama or compatible models with pre-execution AST safety quarantine and bounded test self-repair.
+- ✅ **Runs 100% Locally & Offline:** Requires zero API subscriptions, zero third-party packages, zero account registration, and zero telemetry.
+
+### What Skill Factory Does Not Do
+
+- ❌ **It is not an autonomous "no-code" app creator:** In Offline Mode (`new`, `interview`), Skill Factory generates robust structural scaffolds, validated frontmatter, and test stubs. Domain business logic must be implemented by the developer or by a connected AI assistant.
+- ❌ **It does not invent AI platform features:** It adheres strictly to each platform's documented skill discovery paths and capabilities. It does not force autonomous model invocation on platforms that only support manual slash commands or directory indexing.
+- ❌ **It does not make external network requests:** Skill Factory will never secretly upload your skills, metrics, code, or telemetry to a remote server.
+
+---
+
+## Key Features
+
+- ⚡ **Zero Third-Party Dependencies:** Pure Python standard-library implementation. Runs immediately on any machine with Python 3.9+ without `pip install` friction or virtual environments.
+- 🔒 **Safe & Isolated Execution:** Subprocess test runner enforces an isolated 10-second timeout. Zip archive import strictly validates target paths against Zip-Slip traversal attacks (`../`), and installation defends against symlink escapes.
+- 🎯 **Dual Console Entry Points:** Both `skillfactory` and `skill-factory` CLI commands installed out of the box.
+- 🌐 **8 Supported AI Platforms:** Native discovery and installation for Claude Code, Google Antigravity, Cursor, OpenAI Codex, Windsurf, Continue, Cline, and GitHub Copilot with collision detection and alias normalization.
+- 📦 **Automated Backups & Rollback:** Every update creates an immutable timestamped backup snapshot, enabling instant rollback if a new version breaks existing behavior.
+- 🤖 **Optional AI Engine:** Synthesizes skills from natural language descriptions via local Ollama or OpenAI-compatible endpoints with AST safety interception and up to 3 automated test self-repair retries.
+
+---
+
+## Supported AI Platforms & Verification Levels
+
+Skill Factory maps to official agent discovery paths defined in [`skillfactory/data/platforms.json`](skillfactory/data/platforms.json):
+
+| Platform | Project Scope Folder | Global (User) Scope Folder | Verification Level & Activation Model |
+| :--- | :--- | :--- | :--- |
+| **Claude Code** | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` | **Verified Autonomous Activation:** Host model matches prompt intent to `SKILL.md` description; also supports manual `/<skill-name>` command. |
+| **Google Antigravity** | `.agents/skills/<name>/` | `~/.gemini/config/skills/` | **Verified Autonomous Activation:** Engine injects discovered skills into system prompt `<skills>` context; model autonomously reads `SKILL.md` when intent matches. |
+| **Cursor** | `.agents/skills/<name>/`, `.cursor/skills/` | `~/.agents/skills/`, `~/.cursor/skills/` | **Verified Directory Discovery:** Discovered in workspace or global folder; invoked via manual slash command `/<skill-name>` or explicit `@` context inclusion. |
+| **OpenAI Codex** | `.agents/skills/<name>/` | `~/.agents/skills/` | **Simulated CLI Integration:** Discovered in `.agents/skills/`; invoked via CLI syntax `$<skill-name>`; respects `agents/openai.yaml` metadata. |
+| **Windsurf** | `.codeium/windsurf/skills/<name>/` | `~/.codeium/windsurf/skills/<name>/` | **Verified Directory Discovery:** Discovered in Codeium Cascade workspace configuration. |
+| **Continue** | `.continue/prompts/<name>/` | `~/.continue/prompts/<name>/` | **Verified Prompt / Tool Folder:** Discovered in Continue prompt/custom commands directory. |
+| **Cline** | `.cline/skills/<name>/` | `~/.cline/skills/<name>/` | **Verified Workspace Skill Path:** Discovered in project `.cline/` root directory. |
+| **GitHub Copilot** | `.github/skills/<name>/` | `~/.config/github-copilot/skills/<name>/` | **Verified Repository Instruction Path:** Discovered in `.github/` repository directory. |
+
+Run `skillfactory doctor` to automatically detect which AI assistants are installed on your workstation.
+
+---
+
+## Quickstart
+
+### Prerequisites
+
+Python 3.9 or higher (macOS default Command Line Tools, Linux, or Windows).
+
+### 1. Launch the Interactive Menu (Beginner Friendly)
+
+```bash
+# Clone the repository
+git clone https://github.com/imnashraf/skill-factory.git
+cd skill-factory
+
+# Run the interactive menu (zero flags needed)
+python3 -m skillfactory
+```
+
+*(On Windows, use `py -m skillfactory` or `python -m skillfactory`)*
+
+### 2. Run the Beginner Guided Wizard
+
+```bash
+# Step-by-step walkthrough checking system health, choosing an assistant, and generating a skill
+skillfactory guide
+```
+
+### 3. Install via pip
+
+```bash
+# Install from PyPI
+pip install agent-skill-factory
+
+# Or install locally from source
+pip install .
+
+# Run from anywhere via either command
+skillfactory
+skill-factory
+```
+
+Detailed operating-system walkthroughs:
+
+- 🍏 [macOS Beginner Guide](docs/quickstart/macos.md)
+- 🪟 [Windows Beginner Guide](docs/quickstart/windows.md)
+- 🐧 [Linux Beginner Guide](docs/quickstart/linux.md)
+- 📖 [Comprehensive Beginner Quickstart](docs/beginnerQuickstart.md)
+- 📚 [Beginner Glossary](docs/glossary.md)
+
+---
+
+## End-to-End Walkthrough Examples
+
+### A. Classic Deterministic Creation & Installation
+
+```bash
+# Step 1: Create a new skill
+skillfactory new --name log-summarizer --description "Analyze server logs and output error distribution summaries."
+
+# Step 2: Validate specification compliance, run tests, and evaluate
+skillfactory validate generated-skills/log-summarizer
+skillfactory test generated-skills/log-summarizer
+skillfactory eval generated-skills/log-summarizer
+
+# Step 3: Install the skill into your AI assistant (e.g. Claude Code or Antigravity)
+skillfactory install generated-skills/log-summarizer --platform claude
+
+# Step 4: Verify installed skill status
+skillfactory list
+```
+
+### B. Curated Domain Skill Packs
+
+```bash
+# List all 5 available curated skill packs
+skillfactory pack list
+
+# Install the entire Finance & ERP Pack into Cursor
+skillfactory pack install finance-erp --target cursor
+
+# Verify pack integrity and test coverage
+skillfactory pack verify finance-erp
+```
+
+### C. Optional AI-Assisted Skill Creation
+
+```bash
+# Synthesize a skill from natural language with AST safety interception and bounded self-repair
+skillfactory ai-create "Compare two attendance logs and identify missing employees, duplicate records, and overtime hours" --name attendance-auditor
+```
+
+---
+
+## Curated Domain Skill Packs (14 Reference Skills)
+
+Skill Factory organizes reference skills into a 3-tier taxonomy (**Personal**, **Professional**, **Developer**) across 5 curated packs. Every included skill is tested and scores Grade A (≥90/100):
+
+### 1. Office Productivity Pack (`office-productivity`)
+
+- **Excel Comparison Engine** (`excel-comparison`): Pure standard-library `.xlsx` parser diffing spreadsheets cell-by-cell.
+- **Smart File Organizer & Renamer** (`file-organizer`): Categorizes files by MIME/date with dry-run collision defense.
+- **CSV Analytical Report Generator** (`csv-to-report`): Computes statistical summaries and outputs Markdown, HTML, and JSON.
+- **Markdown Repository Validator** (`markdown-doc-validator`): Detects broken relative file links, unaligned tables, and untagged fences.
+- **Structured Notes Formatter** (`structured-notes-formatter`): Transforms raw meeting notes into structured minutes with action item extraction.
+
+### 2. Finance & ERP Pack (`finance-erp`)
+
+- **Financial Variance Analyzer** (`financial-variance-analyzer`): Compares budget vs. actual figures, flagging percentage and absolute thresholds.
+- **Invoice Reconciliation** (`invoice-reconciliation`): Reconciles vendor invoices against purchase orders, identifying mismatched totals and duplicate line items.
+
+### 3. HR & Workforce Pack (`hr-workforce`)
+
+- **Attendance CSV Validator** (`attendance-csv-validator`): Audits clock-in/out records for anomalies, missing punches, and negative durations.
+- **Timesheet Reconciliation** (`timesheet-reconciliation`): Cross-references contractor timesheets against approved project rosters.
+
+### 4. Project Management Pack (`project-management`)
+
+- **RAID Log Validator** (`raid-log-validator`): Validates Risk, Assumption, Issue, and Dependency matrices against delivery standards.
+- **Project Status Reporter** (`project-status-reporter`): Aggregates sprint updates and milestones into executive Markdown summaries.
+
+### 5. Developer & Security Pack (`developer-security`)
+
+- **Security & Configuration Scanner** (`security-config-scanner`): AST-based scanner detecting exposed API keys and permissive CORS wildcards.
+- **Dependency Manifest Reviewer** (`dependency-manifest-reviewer`): Audits `requirements.txt` and `package.json` for unpinned or insecure dependencies.
+- **Test Inventory Analyzer** (`test-inventory-analyzer`): Inventories automated tests, measuring coverage distribution and skipped test ratios.
+
+---
+
+## CLI Command Reference
+
+All commands are available via `skillfactory <command>` or `skill-factory <command>`:
+
+| Command | Description | Example |
+| --- | --- | --- |
+| `menu` | Opens the interactive numbered menu (default when run without args). | `skillfactory` |
+| `guide` | Step-by-step interactive beginner onboarding wizard. | `skillfactory guide` |
+| `new` | Directly generates a skill with command-line flags. | `skillfactory new --name my-tool --desc "Process log files"` |
+| `interview` | Guided 5-question terminal interview or non-interactive JSON batch. | `skillfactory interview` |
+| `ai-create` | Synthesizes a skill from natural language with AST safety interception. | `skillfactory ai-create "Extract tables from CSV files"` |
+| `pack` | Browse, install, verify, and uninstall curated domain packs. | `skillfactory pack list` |
+| `validate` | Validates YAML frontmatter, naming, structure, and SHA-256 hashes. | `skillfactory validate generated-skills/my-tool` |
+| `doctor` | Inspects workstation, Python runtime, and reports installed AI platforms. | `skillfactory doctor` |
+| `test` | Runs a skill's automated test suite in an isolated subprocess (10s timeout). | `skillfactory test generated-skills/my-tool` |
+| `eval` | Computes 0–100 quality score and letter grade (Grade A–F). | `skillfactory eval generated-skills/my-tool` |
+| `scan` | Scans for dangerous AST calls (`eval`, `exec`, `os.system`), prompt injections, and leaked keys. | `skillfactory scan generated-skills/my-tool` |
+| `install` | Installs a skill into an AI platform with backup snapshotting. | `skillfactory install generated-skills/my-tool --platform cursor` |
+| `list` | Lists all installed skills across all detected platforms. | `skillfactory list` |
+| `update` | Updates an installed skill, detecting local modifications and backing up. | `skillfactory update my-tool --platform cursor` |
+| `rollback` | Restores an installed skill to its previous backup snapshot. | `skillfactory rollback my-tool --platform cursor` |
+| `uninstall` | Safely removes an installed skill, preserving user data files. | `skillfactory uninstall my-tool --platform cursor` |
+| `install-self` | Installs Skill Factory itself into a chosen AI coding assistant. | `skillfactory install-self --platform claude` |
+| `search` | Sub-millisecond offline keyword/tag search on library. | `skillfactory search log` |
+| `export` | Packages a skill into a portable `.zip` with SHA-256 checksum sidecar. | `skillfactory export generated-skills/my-tool` |
+| `import` | Safely extracts a `.zip` skill package with Zip-Slip defense. | `skillfactory import my-tool.zip` |
+| `publish` | Generates a standalone repository with README, LICENSE, and CI. | `skillfactory publish generated-skills/my-tool --out-dir dist/` |
+
+---
+
+## Security & Privacy Model
+
+Skill Factory adheres to strict host isolation and safety guarantees:
+
+- **Local-First & Zero-Telemetry:** All operations execute locally. No code, skill names, descriptions, or parameters are ever transmitted over the network.
+- **AST Danger Detection:** Source code is analyzed using Python's abstract syntax tree before execution to intercept forbidden patterns (`eval`, `exec`, `os.system`, `subprocess` with `shell=True`, and recursive filesystem deletions).
+- **Prompt Injection Defense:** Multi-vector screening detects directive overrides, persona hijacks, hidden markup, exfiltration endpoints, and system prompt extraction attacks.
+- **Symlink Escape Defense:** File copying and packaging strictly verify that symlinks do not escape the skill folder boundary to access sensitive host files.
+- **Secrets & Credential Scanner:** Detects exposed AWS keys, GitHub tokens, OpenAI/Anthropic API keys, and PEM certificates.
+- **Atomic Staging:** Files are generated in sibling staging directories (`.tmp-<uuid>`) and atomically renamed only upon successful manifest generation, preventing corrupt or half-written skills.
+- **Zip-Slip Defense:** Archive extraction strictly verifies resolved destination paths to prevent path traversal attacks (`../`).
+- **Subprocess Isolation:** Test execution runs in an isolated child process with a strict 10-second timeout, preventing hanging processes or memory exhaustion.
+
+Review our full [Security Policy](SECURITY.md) and [Security Architecture](docs/securityAndPrivacy.md) for vulnerability reporting and threat modeling.
+
+---
+
+## Troubleshooting & FAQ
+
+### 1. `python3: command not found` (Windows)
+
+On Windows, the default Python launcher is `py`. Use:
+
+```cmd
+py -m skillfactory
+```
+
+Or ensure Python is added to your system `PATH` in the Windows installer.
+
+### 2. "Destination already exists and is not managed by Skill Factory"
+
+Skill Factory protects your pre-existing files. If a directory was created manually, Skill Factory refuses to overwrite it. To overwrite an unmanaged directory, pass `--force`:
+
+```bash
+skillfactory install generated-skills/my-skill --platform claude --force
+```
+
+### 3. "Skill has local modifications. Use --force to overwrite"
+
+During `update`, Skill Factory checks current files against the original cryptographic manifest. If you edited files manually, it alerts you to prevent accidental data loss. Passing `--force` creates a backup snapshot and updates the files.
+
+### 4. How do I test backward compatibility?
+
+Skill Factory preserves full backward compatibility with the legacy Phase 0 generator:
+
+```bash
+python3 scripts/create_skill.py --name test-skill --description "Testing backward compatibility"
+```
+
+---
+
+## Governance & Contributing
+
+Skill Factory is an open-source project welcoming community contributions. Please review:
+
+- [Contributing Guidelines](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Architecture Decisions Log](docs/decisions.md)
+- [Security Policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+---
+
+## License
+
+MIT License. Copyright (c) 2026 Skill Factory Contributors.
+
+All skills generated by Skill Factory are the **100% exclusive property of the user** under whichever license the user selects. Skill Factory does not require viral attribution in your generated skills.