@skilly-hand/skilly-hand 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [Unreleased]
+
+### Added
+- Added automated changelog rotation via `scripts/release-changelog.mjs` to create dated release sections with npm version links.
+
+### Changed
+- Updated release workflow documentation and publish validation to include `CHANGELOG.md`.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._

package/LICENSE

@@ -0,0 +1,23 @@
+Creative Commons Attribution-NonCommercial 4.0 International
+
+Copyright (c) 2026 skilly-hand contributors
+
+This work is licensed under the Creative Commons Attribution-NonCommercial
+4.0 International License (CC BY-NC 4.0).
+
+You are free to:
+- Share: copy and redistribute the material in any medium or format
+- Adapt: remix, transform, and build upon the material
+
+Under the following terms:
+- Attribution: You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made.
+- NonCommercial: You may not use the material for commercial purposes.
+- No additional restrictions: You may not apply legal terms or technological
+  measures that legally restrict others from doing anything the license permits.
+
+License details:
+https://creativecommons.org/licenses/by-nc/4.0/
+
+Full legal code:
+https://creativecommons.org/licenses/by-nc/4.0/legalcode

package/README.md

@@ -0,0 +1,107 @@
+<div align="center">
+
+```text
+ ██████╗██╗  ██╗██╗██╗     ██╗     ██╗   ██╗    ██╗  ██╗ █████╗ ███╗   ██╗██████╗
+██╔════╝██║ ██╔╝██║██║     ██║     ╚██╗ ██╔╝    ██║  ██║██╔══██╗████╗  ██║██╔══██╗
+╚█████╗ █████╔╝ ██║██║     ██║      ╚████╔╝     ███████║███████║██╔██╗ ██║██║  ██║
+ ╚══██╗ ██╔═██╗ ██║██║     ██║       ╚██╔╝      ██╔══██║██╔══██║██║╚██╗██║██║  ██║
+██████╔╝██║  ██╗██║███████╗███████╗   ██║        ██║  ██║██║  ██║██║ ╚████║██████╔╝
+╚═════╝ ╚═╝  ╚═╝╚═╝╚══════╝╚══════╝   ╚═╝        ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝
+```
+
+**Portable AI agent skills. One CLI. Every coding assistant.**
+
+[![npm](https://img.shields.io/npm/v/%40skilly-hand%2Fskilly-hand?style=flat-square&color=black&label=npm)](https://www.npmjs.com/package/@skilly-hand/skilly-hand)
+[![license](https://img.shields.io/badge/license-CC--BY--NC--4.0-black?style=flat-square)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-black?style=flat-square)](https://nodejs.org)
+[![ESM](https://img.shields.io/badge/ESM-native-black?style=flat-square)](https://nodejs.org/api/esm.html)
+
+</div>
+
+---
+
+## What it does
+
+- **Installs portable AI agent skills** into your project from a curated catalog
+- **Auto-detects your stack** and recommends relevant skills automatically
+- **Supports every major coding assistant** — Claude Code, OpenCode, Cursor, Copilot, Gemini, and Codex — from a single command
+- **Preserves original agentic structures** in `source/legacy/` as a migration reference
+
+---
+
+## Quick Start
+
+```bash
+npm install
+npx skilly-hand
+```
+
+---
+
+## Commands
+
+| Command | Description |
+| ------- | ----------- |
+| `npx skilly-hand install` | Install skills into the current project |
+| `npx skilly-hand detect` | Auto-detect project stack and suggest skills |
+| `npx skilly-hand list` | List all available skills in the catalog |
+| `npx skilly-hand doctor` | Diagnose installation and configuration issues |
+| `npx skilly-hand uninstall` | Remove installed skills |
+
+---
+
+## Release Workflow (npm)
+
+1. Confirm session: `npm whoami` (or `npm login`).
+2. Keep `CHANGELOG.md` up to date under `## [Unreleased]` as work lands.
+3. Regenerate derived catalog files when needed: `npm run build && npm run catalog:sync`.
+4. Run publish gate: `npm run verify:publish`.
+5. Inspect package payload: `npm pack --dry-run --json`.
+6. Bump version intentionally: `npm version patch|minor|major` (this auto-rotates `CHANGELOG.md`, creates a dated release section, and inserts a version-specific npm link).
+7. Publish the root package: `npm publish` (or `npm publish --tag next` for prereleases).
+8. Smoke test after publish: `npx @skilly-hand/skilly-hand@<version> --help`.
+9. Verify npm metadata (README render, changelog, license, executable bin).
+
+---
+
+## Stack Detection
+
+Automatic detection covers the most common Node.js stacks:
+
+Node.js · TypeScript · React · Next.js · Angular · Vite · Playwright · Vitest · Tailwind CSS · Storybook
+
+---
+
+## Supported Assistants
+
+Skills are installed into `.skilly-hand/` with the correct format for each tool:
+
+| Tool | Install Target |
+| ---- | -------------- |
+| Claude Code / OpenCode | `.claude/skills/` |
+| Cursor | `.cursor/skills/` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Gemini CLI | `.gemini/skills/` |
+| Codex (OpenAI) | `.codex/skills/` |
+
+---
+
+## Project Structure
+
+```text
+catalog/
+  skills/               # portable skill catalog published by the CLI
+packages/
+  cli/                  # main binary
+  core/                 # installation, rendering, and restore logic
+  detectors/            # stack auto-detection
+  catalog/              # catalog access and validation
+source/legacy/
+  agentic-structure/    # original material preserved as reference
+tests/
+  fixtures/             # simulated repos for integration testing
+```
+
+---
+
+Licensed under [CC BY-NC 4.0](./LICENSE).

package/catalog/README.md

@@ -0,0 +1,30 @@
+<div align="center">
+
+# Portable Skill Catalog
+
+*Published portable skills consumed by the `skilly-hand` CLI.*
+
+</div>
+
+---
+
+## Skills
+
+| Skill | Description | Tags |
+| ----- | ----------- | ---- |
+| `agents-root-orchestrator` | Author root `AGENTS.md` as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | `core` `workflow` `orchestration` |
+| `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | `core` `workflow` `authoring` |
+| `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | `core` `workflow` `planning` |
+| `token-optimizer` | Classify task complexity and right-size reasoning depth, context gathering, and response detail to reduce wasted tokens. | `core` `workflow` `efficiency` |
+
+---
+
+## Install a skill
+
+```bash
+npx skilly-hand install <skill-name>
+npx skilly-hand install agents-root-orchestrator
+```
+
+> [!NOTE]
+> Legacy source under `source/legacy/agentic-structure` is preserved as reference material and is **excluded from installation**.

package/catalog/catalog-index.json

@@ -0,0 +1,6 @@
+[
+  "agents-root-orchestrator",
+  "skill-creator",
+  "spec-driven-development",
+  "token-optimizer"
+]

package/catalog/skills/agents-root-orchestrator/SKILL.md

@@ -0,0 +1,135 @@
+# AGENTS Root Orchestrator Guide
+
+## When to Use
+
+Use this skill when:
+
+- Creating a new root `AGENTS.md` for a repository.
+- Refactoring root AI instructions that have grown inconsistent.
+- Converting scattered guidance into a single routing guide.
+- Defining explicit trigger-based skill invocation behavior.
+
+Do not use this skill for:
+
+- Subfolder-only guides that inherit from parent AGENTS files.
+- One-off prompt notes with no reusable routing value.
+- Agent-specific mirror files (`CLAUDE.md`, `GEMINI.md`) as primary source.
+
+---
+
+## Core Structure: Where / What / When
+
+### Where (Context and Boundaries)
+
+Define where the guide applies and where to escalate:
+
+- Repository scope and ownership boundaries.
+- Folder map and key domains.
+- Escalation path when a task exceeds local scope.
+
+### What (Capabilities and Routing)
+
+Define what AI should use:
+
+- Installed skill registry with concise purpose.
+- Role-oriented routing tables (task -> skill chain).
+- Non-negotiable rules and default conventions.
+
+### When (Triggers and Sequencing)
+
+Define when skills must be invoked:
+
+- Auto-invoke trigger table by action.
+- Ordered workflow chains for recurring tasks.
+- Prerequisite rules so downstream skills are never invoked first.
+
+### Chaining Notations (Workflow Composition)
+
+Define integrated multi-skill chains using explicit notation:
+
+- Use `->` to document prerequisite order.
+- Keep each chain named and scoped to one repeated workflow.
+- Add a one-line "when to use" note after each chain.
+- Treat earlier steps as mandatory unless explicitly marked optional.
+
+---
+
+## Decision Tree
+
+```text
+Is this the repository-wide instruction entry point?
+  YES -> Create/update root AGENTS.md with Where/What/When
+  NO  -> Use subfolder AGENTS conventions and inherit parent rules
+
+Does the task require routing across multiple skill types?
+  YES -> Add Task -> Skill chain table in What
+  NO  -> Keep concise capability list and direct triggers
+
+Are trigger conditions currently implicit or ambiguous?
+  YES -> Add explicit action-based trigger rows in When
+  NO  -> Keep existing triggers but normalize wording
+```
+
+---
+
+## Example Outline
+
+### Example 1: Where Section
+
+```markdown
+## Where
+
+- Scope: repository root and all descendant folders unless overridden.
+- Primary map: app code in `src/`, automation in `scripts/`, tests in `tests/`.
+- Escalate to maintainers when task changes CI, security, or release flows.
+```
+
+### Example 2: When Section
+
+```markdown
+## When
+
+| Action | Skill |
+| ------ | ----- |
+| Planning multi-step feature work | `spec-driven-development` |
+| Creating new reusable skill instructions | `skill-creator` |
+| Updating root AGENTS orchestration map | `agents-root-orchestrator` |
+```
+
+### Example 3: Chaining Notations Section
+
+````markdown
+## Chaining Notations
+
+Chaining notations document integrated workflows where multiple skills are sequentially invoked for complex tasks. Always invoke skills in documented order.
+
+### Skill Creation Workflow
+
+```text
+Asking for a new skill
+  -> skill-creator
+  -> spec-driven-development
+  -> agents-root-orchestrator
+```
+
+When to use: creating and registering a new reusable skill workflow.
+````
+
+---
+
+## Commands
+
+```bash
+mkdir -p .skilly-hand/catalog/agents-root-orchestrator/assets
+cp .skilly-hand/catalog/agents-root-orchestrator/assets/AGENTS-ROOT-TEMPLATE.md AGENTS.md
+npx skilly-hand install --dry-run
+```
+
+---
+
+## Resources
+
+- Template: [assets/AGENTS-ROOT-TEMPLATE.md](assets/AGENTS-ROOT-TEMPLATE.md)
+- Companion skills:
+  - [../skill-creator/SKILL.md](../skill-creator/SKILL.md)
+  - [../spec-driven-development/SKILL.md](../spec-driven-development/SKILL.md)

package/catalog/skills/agents-root-orchestrator/assets/AGENTS-ROOT-TEMPLATE.md

@@ -0,0 +1,67 @@
+# {{projectName}} AI Agent Orchestrator
+
+> Root guidance for repository-wide AI routing. This file defines where work belongs, what capabilities to invoke, and when triggers apply.
+
+## Where
+
+- **Scope**: Repository root and all descendants unless a deeper `AGENTS.md` overrides locally.
+- **Folder Map**:
+  - `src/` -> application and feature implementation.
+  - `tests/` -> automated verification and integration coverage.
+  - `scripts/` -> operational automation and maintenance flows.
+- **Escalation**: For cross-cutting architecture, CI/CD, or policy changes, route to maintainers before implementation.
+
+## What
+
+### Installed Skill Registry
+
+| Skill | Purpose | Tags |
+| ----- | ------- | ---- |
+{{skillsTable}}
+
+### Task Routing
+
+| Task Type | Recommended Skill Chain |
+| --------- | ----------------------- |
+| Multi-step planning | `spec-driven-development` |
+| Creating/updating reusable skills | `skill-creator` |
+| Root AGENTS orchestration updates | `agents-root-orchestrator` |
+
+## When
+
+### Auto-invoke Triggers
+
+| Action | Skill |
+| ------ | ----- |
+{{autoInvokeTable}}
+
+### Sequencing Rules
+
+1. Classify task complexity first.
+2. Invoke prerequisite skills before implementation skills.
+3. Verify outcomes and update routing guidance when workflow changes.
+
+## Chaining Notations
+
+Chaining notations document integrated workflows where multiple skills are sequentially invoked for complex tasks. Always invoke skills in documented order.
+
+### Root Orchestration Maintenance Workflow
+
+```text
+Updating root AGENTS orchestration guidance
+  -> agents-root-orchestrator
+  -> skill-creator (if workflow guidance changes)
+```
+
+When to use: maintaining repository-level routing, trigger, and escalation guidance.
+
+### Skill Introduction Workflow
+
+```text
+Asking for a new reusable skill
+  -> skill-creator
+  -> spec-driven-development
+  -> agents-root-orchestrator
+```
+
+When to use: introducing a new catalogued skill and registering it in root orchestration guidance.

package/catalog/skills/agents-root-orchestrator/manifest.json

@@ -0,0 +1,34 @@
+{
+  "id": "agents-root-orchestrator",
+  "title": "AGENTS Root Orchestrator",
+  "description": "Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly.",
+  "portable": true,
+  "tags": ["core", "workflow", "orchestration"],
+  "detectors": ["always"],
+  "detectionTriggers": ["always"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-04-03",
+    "license": "Apache-2.0",
+    "version": "1.0.0",
+    "changelog": "Added root AGENTS orchestration guidance around Where/What/When structure; improves AI task routing clarity and trigger recognition; affects root AGENTS authoring workflow",
+    "auto-invoke": "Creating or updating root AGENTS.md orchestration guidance",
+    "allowed-tools": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash",
+      "Task",
+      "SubAgent"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "assets/AGENTS-ROOT-TEMPLATE.md", "kind": "asset" }
+  ],
+  "dependencies": []
+}

package/catalog/skills/skill-creator/SKILL.md

@@ -0,0 +1,176 @@
+# Skill Creator Guide
+
+## When to Create a Skill
+
+Create a skill when:
+
+- A pattern is used repeatedly and AI needs guidance.
+- Project-specific conventions differ from generic best practices.
+- Complex workflows need step-by-step instructions.
+- Decision trees help AI choose the right approach.
+
+Do not create a skill when:
+
+- Documentation already exists and a reference is enough.
+- The pattern is trivial or self-explanatory.
+- It is a one-off task.
+
+---
+
+## Skill Structure
+
+```text
+skills/{skill-name}/
+├── SKILL.md              # Required - main skill file
+├── assets/               # Optional - templates, schemas, examples
+│   ├── template.py
+│   └── schema.json
+├── agents/               # Optional - sub-agents for complex skills
+│   ├── agent1/
+│   │   └── SKILL.md
+│   └── agent2/
+│       └── SKILL.md
+└── references/           # Optional - links to local docs
+    └── docs.md
+```
+
+---
+
+## Naming Conventions
+
+| Type | Pattern | Examples |
+|------|---------|----------|
+| Generic skill | `{technology}` | `pytest`, `playwright`, `typescript` |
+| `{product-name}`-specific | `{product-name}-{purpose}` | `{product-name}-best-practices`, `{product-name}-code-connect`, `{product-name}-a11y-checker` |
+| `{product-name}` testing | `{product-name}-{function}-{target}` | `{product-name}-unit-test`, `{product-name}-token-audit` |
+| Workflow skill | `{action}-{target}` | `skill-creator`, `commit-writer`, `pr-writer` |
+
+---
+
+## Decision: assets/ vs references/ vs agents/
+
+```text
+Need code templates?        -> assets/
+Need JSON schemas?          -> assets/
+Need example configs?       -> assets/
+Link to existing docs?      -> references/
+Link to external guides?    -> references/ (with local path)
+Skill needs sub-agents?     -> agents/
+```
+
+Key Rule: `references/` should point to local files, not web URLs.
+
+---
+
+## Decision: `{product-name}`-Specific vs Generic
+
+```text
+Patterns apply to any project?             -> Generic skill (e.g., pytest, typescript)
+Patterns are {product-name}-specific?      -> {product-name}-{name} skill
+Generic skill needs {product-name} info?   -> Add references/ pointing to {product-name} docs
+```
+
+---
+
+## Frontmatter Fields
+
+| Field | Required | Format | Description |
+|-------|----------|--------|-------------|
+| `name` | Yes | `lowercase-hyphens` | Skill identifier |
+| `description` | Yes | Block with trigger | What skill does plus explicit `Trigger: ...` clause for AI recognition |
+| `metadata.author` | Yes | String | Always `skilly-hand` |
+| `metadata.last-edit` | Yes | ISO 8601 date | Format: `YYYY-MM-DD` (e.g., `2026-03-21`) |
+| `metadata.license` | Yes | String | Always `Apache-2.0` for `skilly-hand` |
+| `metadata.version` | Yes | Semantic version | Format: `"X.Y.Z"` as string |
+| `metadata.changelog` | Yes | Structured text | Format: `"<what changed>; <why it matters>; <where it affects>"` |
+| `metadata.auto-invoke` | Yes | String | Explicit trigger condition (e.g., `"When auditing, reviewing, or validating an existing skill"`) |
+| `allowed-tools` | Yes | Comma-separated | All tools this skill can invoke (e.g., `Read, Edit, Write, SubAgent`) |
+| `allowed-modes` | Optional | YAML list | Use only when skill has an `agents/` folder |
+
+---
+
+## Metadata Standards
+
+### Changelog Format Structure
+
+Use this structure:
+
+```text
+"<what changed>; <why it matters>; <where it affects>"
+```
+
+Example:
+
+```text
+"Added integrated metadata validation guidance; improves consistency and reviewability; affects skill quality checks and maintenance workflows"
+```
+
+Guidelines:
+
+- What changed: Be specific about the modification.
+- Why it matters: Explain business or technical value.
+- Where it affects: Document impact area.
+
+### last-edit Format
+
+Always use ISO 8601 date format: `YYYY-MM-DD` (e.g., `2026-03-21`).
+
+### allowed-modes Field Rule
+
+Include `allowed-modes` only when your skill has an `agents/` subfolder with sub-agents.
+
+Include it when:
+
+- The skill orchestrates multiple specialized sub-agents.
+- Each sub-agent has its own `SKILL.md` under `skills/{skill-name}/agents/{subagent-name}/`.
+- Different modes delegate to different sub-agents.
+
+Omit it when:
+
+- The skill has no `agents/` folder.
+- The skill behaves the same regardless of mode.
+
+---
+
+## Content Guidelines
+
+Do:
+
+- Start with the most critical patterns.
+- Use tables for decision trees.
+- Keep code examples minimal and focused.
+- Include a Commands section with copy-paste commands.
+- Use ISO 8601 format for all dates (`YYYY-MM-DD`).
+- Include explicit `Trigger:` clause in description for AI recognition.
+- Add `allowed-modes` only if the skill has `agents/` with sub-agents.
+
+Do not:
+
+- Add a Keywords section (agent searches frontmatter, not body).
+- Duplicate content from existing docs (reference instead).
+- Include lengthy explanations when a concise rule is enough.
+- Add troubleshooting sections when they are not essential.
+- Use web URLs in references.
+- Leave `changelog` empty or informal.
+- Use non-ISO date formats.
+
+---
+
+## Checklist Before Creating
+
+- [ ] Skill does not already exist.
+- [ ] Pattern is reusable (not one-off).
+- [ ] Name follows conventions.
+- [ ] Frontmatter includes all required fields.
+- [ ] `description` includes explicit `Trigger: ...` clause.
+- [ ] `last-edit` uses ISO format (`YYYY-MM-DD`).
+- [ ] `changelog` uses structured format: `what; why; where`.
+- [ ] `allowed-modes` is present only when `agents/` exists.
+- [ ] `allowed-tools` matches actual tool usage.
+- [ ] Critical patterns are clear and concise.
+- [ ] Code examples are minimal and focused.
+- [ ] Commands section exists with copy-paste commands.
+
+## Resources
+
+- Template: [assets/SKILL-TEMPLATE.md](assets/SKILL-TEMPLATE.md)

package/catalog/skills/skill-creator/assets/SKILL-TEMPLATE.md

@@ -0,0 +1,94 @@
+---
+name: {skill-name}
+description: >
+  {Brief description of what this skill enables}.
+  Trigger: {When the AI should load this skill - explicit trigger condition}.
+metadata:
+  author: skilly-hand
+  last-edit: {YYYY-MM-DD}
+  license: Apache-2.0
+  version: "1.0.0"
+  changelog: "{<what changed>; <why it matters>; <where it affects>}"
+  auto-invoke: "{Complete with a brief and specific phrase if the skill needs auto-invoke}"
+allowed-tools: {tool1, tool2, tool3}  # Examples: Read, Edit, Write, Bash, Grep, SubAgent, Task, WebFetch
+# IMPORTANT: Only include 'allowed-modes' if your skill has an agents/ folder with sub-agents.
+# If you don't have agents/, delete the lines below.
+allowed-modes:
+  - {mode-name}     # {Description of when this mode is used}
+---
+
+# {Name of the Skill} Guide
+
+## When to Use
+
+Use this skill when:
+
+- {Condition 1}.
+- {Condition 2}.
+- {Condition 3}.
+
+Do not use this skill for:
+
+- {Condition 1}.
+- {Condition 2}.
+- {Condition 3}.
+
+---
+
+## Critical Patterns
+
+{The most important rules the AI must follow}
+
+### Pattern 1: {Name}
+
+```{language}
+{code example}
+```
+
+### Pattern 2: {Name}
+
+```{language}
+{code example}
+```
+
+---
+
+## Decision Tree
+
+```text
+{Question 1}? -> {Action A}
+{Question 2}? -> {Action B}
+Otherwise     -> {Default action}
+```
+
+---
+
+## Code Examples
+
+### Example 1: {Description}
+
+```{language}
+{minimal, focused example}
+```
+
+### Example 2: {Description}
+
+```{language}
+{minimal, focused example}
+```
+
+---
+
+## Commands
+
+```bash
+{command 1} # {description}
+{command 2} # {description}
+{command 3} # {description}
+```
+
+---
+
+## Resources
+
+- Template assets: Place reusable templates, schemas, and examples in `assets/`.