@mhmdreza-rafiei/agentry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 comprehensive-skills 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.

package/README.md

@@ -0,0 +1,95 @@
+# agentry
+
+A raw installer for AI/agent tooling. `agentry` fetches **agents, skills, rules, and scripts** from any Git repo (or local path) and installs the ones you pick into your project — or globally — under `.cursor/`. The CLI ships no assets of its own; you point it at a source.
+
+## Install / run
+
+```bash
+# Run without installing (recommended)
+npx agentry@latest --help
+
+# Or install the CLI globally
+npm install -g agentry@latest
+
+# Update / uninstall the CLI
+agentry update
+agentry --uninstall
+```
+
+> Publishing to npm is pending. Until then, run from a clone: `node bin/agentry.js …` or `npx . …`.
+
+## Usage
+
+```
+agentry add <type> <source> [category/name | category] [options]
+agentry add profile <name> [source] [options]
+agentry remove <type> [category/name | category] [options]
+agentry list <source> [type]
+agentry update
+```
+
+`<source>` is a GitHub shorthand `author/repo`, a full git URL, or a local path.
+
+```bash
+agentry add skills Prat011/awesome-llm-skills                    # list all skills and pick
+agentry add skills Prat011/awesome-llm-skills video-downloader   # one skill (no category)
+agentry add skills Prat011/awesome-llm-skills document-skills/docx  # one skill (category/name)
+agentry add agents author/repo frontend                         # a whole category
+agentry add profile frontend author/repo                        # apply profile/frontend.json
+agentry remove skills document-skills/docx                      # remove an installed asset
+agentry list Prat011/awesome-llm-skills
+```
+
+Flags: `-g, --global` (into `~/.cursor`), `--project` (current folder, default), `--dir <path>`, `-y, --yes` (no prompts; install everything matched), `-v, --version`, `-h, --help`, `--uninstall`.
+
+When neither `--global` nor `--project` is given, an interactive terminal asks where to install; non‑interactive runs (agents/CI) default to the current project.
+
+## How sources are discovered
+
+For each type, `agentry` finds assets in two ways and merges them:
+
+1. Under an explicit folder — `<type>/<name>/` or `<type>/<category>/<name>/`.
+2. At the repo root by marker file (like `npx skills add`) — a folder with `SKILL.md` is a skill, `AGENT.md` an agent, `RULE.md` a rule. A root folder whose children carry markers becomes a category (e.g. `document-skills/docx`).
+
+Selectors after the source: `category/name` (one asset), `name` (one asset when uncategorized), `category` (whole category), or omit to list-and-pick.
+
+Assets install to `<root>/.cursor/<type>/[category/]<name>/` and are tracked in `.cursor/agentry.lock.json` for idempotent installs and clean removal. `remove` works purely on installed files, so it needs no source.
+
+## Profiles
+
+A profile is a plain JSON file at `profile/<name>.json` in your project. It lists selectors per type; `agentry add profile <name> <source>` fetches the source once and installs everything the profile lists.
+
+```json
+{
+  "repo": "author/repo",
+  "agents":  ["frontend"],
+  "skills":  ["prompt/enhance-prompt"],
+  "rules":   ["workflow/ask-dont-guess"]
+}
+```
+
+`repo` is optional — the command-line `<source>` wins when given. See [`profile/frontend.json`](profile/frontend.json) and [`profile/backend.json`](profile/backend.json).
+
+## Publish to npm (maintainers)
+
+```bash
+# ensure package.json "name" is available (or scope it: @you/agentry)
+npm login
+npm publish --access public
+# verify
+npx agentry@latest --version
+```
+
+## Development / test
+
+```bash
+npm test                 # node --test (discovery, source resolution, install/remove, profiles)
+node bin/agentry.js …    # run the CLI locally
+node bin/agentry.js list ./examples   # try it against the bundled sample source
+```
+
+`examples/` is a sample source repo (skills/agents/rules/scripts) used by the demo — not part of the CLI. `src/` holds the logic: `registry` (discovery), `source` (fetch), `commands` (install/remove), `profile` (config).
+
+## License
+
+MIT

package/bin/agentry.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+'use strict';
+
+const readline = require('node:readline');
+const { execSync } = require('node:child_process');
+const reg = require('../src/registry');
+const src = require('../src/source');
+const prof = require('../src/profile');
+const cmd = require('../src/commands');
+const pkg = require('../package.json');
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-g' || a === '--global') flags.global = true;
+    else if (a === '--project') flags.project = true;
+    else if (a === '-y' || a === '--yes') flags.yes = true;
+    else if (a === '--dir') flags.dir = argv[++i];
+    else if (a === '-v' || a === '--version') flags.version = true;
+    else if (a === '-h' || a === '--help') flags.help = true;
+    else if (a === '--uninstall') flags.uninstall = true;
+    else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+const HELP = `agentry — a raw installer for agents, skills, rules, and scripts from any repo.
+
+Usage:
+  agentry add <type> <source> [category/name | category] [options]
+  agentry add profile <name> [source] [options]
+  agentry remove <type> [category/name | category] [options]
+  agentry list <source> [type]
+  agentry update
+
+Sources:
+  author/repo        GitHub shorthand      e.g. Prat011/awesome-llm-skills
+  https://…/repo.git full git URL
+  ./path             a local directory
+
+Selectors (after the source):
+  category/name   one asset      e.g. video/downloader
+  name            one asset      (when the repo has no categories)
+  category        a whole category
+  (omitted)       list assets and pick interactively
+
+Examples:
+  agentry add skills Prat011/awesome-llm-skills                    # pick from all skills
+  agentry add skills Prat011/awesome-llm-skills video/downloader   # one skill (categorized)
+  agentry add skills Prat011/awesome-llm-skills video-downloader   # one skill (no category)
+  agentry add agents author/repo frontend                         # a whole category
+  agentry add profile frontend author/repo                        # apply profile/frontend.json
+  agentry remove skills video/downloader                          # remove installed asset
+  agentry list author/repo
+
+Options:
+  -g, --global     Install into ~/.cursor (all projects)
+      --project    Install into the current folder (default)
+      --dir <p>    Install into a specific folder
+  -y, --yes        Don't prompt; install everything matched
+  -v, --version    Print version
+  -h, --help       Show this help
+      --uninstall  Uninstall the agentry CLI`;
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function interactive(flags) {
+  return process.stdin.isTTY && !flags.yes;
+}
+
+async function resolveTarget(flags) {
+  if (flags.global) return { global: true };
+  if (flags.project || flags.dir) return { global: false, dir: flags.dir };
+  if (interactive(flags)) {
+    const ans = await ask('Install location — [P]roject (this folder) or [g]lobal (home)? ');
+    if (/^g/i.test(ans)) return { global: true };
+  }
+  return { global: false };
+}
+
+async function pick(assets) {
+  console.log('Available:');
+  assets.forEach((a, i) => {
+    const desc = (a.description || '').replace(/\s+/g, ' ').slice(0, 60);
+    console.log(`  [${i + 1}] ${a.type}/${a.id}${desc ? ' — ' + desc : ''}`);
+  });
+  const ans = await ask('Install which? (numbers comma-separated, or "all"): ');
+  if (!ans || /^all$/i.test(ans)) return assets;
+  const idx = ans
+    .split(/[, ]+/)
+    .map((s) => parseInt(s, 10) - 1)
+    .filter((n) => n >= 0 && n < assets.length);
+  return idx.map((i) => assets[i]);
+}
+
+function locationLabel(opts) {
+  return opts.global ? 'globally (~/.cursor)' : `project (${cmd.targetRoot(opts)})`;
+}
+
+function dedupe(assets) {
+  const seen = new Set();
+  return assets.filter((a) => {
+    const key = `${a.type}/${a.id}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function installAll(assets, opts) {
+  if (!assets.length) {
+    console.log('Nothing matched — nothing installed.');
+    return;
+  }
+  console.log(`Installing ${assets.length} item(s) ${locationLabel(opts)}:`);
+  for (const a of assets) {
+    const dest = cmd.installOne(a, opts);
+    console.log(`  + ${a.type}/${a.id} -> ${dest}`);
+  }
+  console.log('\nDone. Review assets before use; they run with full agent permissions.');
+}
+
+async function addType(type, source, selector, flags) {
+  if (!source) throw new Error(`Missing source. e.g. agentry add ${type} author/repo`);
+  const opts = await resolveTarget(flags);
+  const { root, cleanup } = src.resolveSource(source);
+  try {
+    let assets = type === 'all' ? reg.allAssets(root) : reg.select(root, type, selector);
+    if (!assets.length) throw new Error(`Nothing found for "${type}${selector ? ' ' + selector : ''}" in ${source}.`);
+    if (!selector && type !== 'all' && assets.length > 1 && interactive(flags)) assets = await pick(assets);
+    installAll(assets, opts);
+  } finally {
+    cleanup();
+  }
+}
+
+async function addProfile(name, source, flags) {
+  const { file, cfg } = prof.loadProfile(name);
+  const repo = source || cfg.repo;
+  if (!repo) throw new Error(`No source given and ${file} has no "repo". Try: agentry add profile ${name} author/repo`);
+  const opts = await resolveTarget(flags);
+  const { root, cleanup } = src.resolveSource(repo);
+  try {
+    const assets = [];
+    for (const type of reg.TYPES) {
+      for (const selector of cfg[type] || []) assets.push(...reg.select(root, type, selector));
+    }
+    installAll(dedupe(assets), opts);
+  } finally {
+    cleanup();
+  }
+}
+
+function listSource(source, type) {
+  if (!source) throw new Error('Missing source. e.g. agentry list author/repo');
+  const { root, cleanup } = src.resolveSource(source);
+  try {
+    for (const t of type ? [type] : reg.TYPES) {
+      console.log(`\n${t}:`);
+      const items = reg.listType(root, t);
+      if (!items.length) {
+        console.log('  (none)');
+        continue;
+      }
+      for (const it of items) {
+        const desc = (it.description || '').replace(/\s+/g, ' ').slice(0, 80);
+        console.log(`  ${it.id}${desc ? ' — ' + desc : ''}`);
+      }
+    }
+  } finally {
+    cleanup();
+  }
+}
+
+async function remove(type, selector, flags) {
+  const opts = await resolveTarget(flags);
+  const scope = [type, selector].filter(Boolean).join('/');
+  if (type === 'all') {
+    let count = 0;
+    for (const t of reg.TYPES) count += cmd.removeSelection(t, undefined, opts).removedKeys.length;
+    console.log(`Removed ${count} item(s) from ${locationLabel(opts)}.`);
+    return;
+  }
+  const r = cmd.removeSelection(type, selector, opts);
+  if (!r.existed && r.removedKeys.length === 0) {
+    console.log(`Nothing installed at "${scope}" in ${locationLabel(opts)}.`);
+    return;
+  }
+  for (const k of r.removedKeys) console.log(`removed ${k}`);
+  console.log(`\nRemoved ${r.removedKeys.length || 1} item(s) from ${locationLabel(opts)}.`);
+}
+
+function runUpdate() {
+  console.log('Updating agentry CLI...');
+  try {
+    execSync('npm install -g agentry@latest', { stdio: 'inherit' });
+  } catch {
+    console.error('Update failed. Once published, run: npm install -g agentry@latest');
+    process.exit(1);
+  }
+}
+
+function runUninstall() {
+  console.log('Uninstalling agentry CLI...');
+  try {
+    execSync('npm uninstall -g agentry', { stdio: 'inherit' });
+  } catch {
+    console.error('Uninstall failed. Try: npm uninstall -g agentry');
+    process.exit(1);
+  }
+}
+
+async function main() {
+  const { flags, positional } = parseArgs(process.argv.slice(2));
+
+  if (flags.version) return console.log(pkg.version);
+  if (flags.uninstall) return runUninstall();
+  if (flags.help || positional.length === 0) return console.log(HELP);
+
+  const [action] = positional;
+
+  if (action === 'update') return runUpdate();
+  if (action === 'list') return listSource(positional[1], positional[2]);
+
+  if (action === 'add') {
+    const type = positional[1];
+    if (!type) throw new Error('Missing type. e.g. agentry add skills author/repo');
+    if (type === 'profile') return addProfile(positional[2], positional[3], flags);
+    if (type !== 'all' && !reg.TYPES.includes(type)) throw new Error(`Unknown type: ${type}`);
+    return addType(type, positional[2], positional[3], flags);
+  }
+
+  if (action === 'remove') {
+    const type = positional[1];
+    if (!type) throw new Error('Missing type. e.g. agentry remove skills video/downloader');
+    if (type !== 'all' && !reg.TYPES.includes(type)) throw new Error(`Unknown type: ${type}`);
+    return remove(type, positional[2], flags);
+  }
+
+  console.error(`Unknown action: ${action}\n\n${HELP}`);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/examples/agents/frontend/frontend-developer/AGENT.md

@@ -0,0 +1,17 @@
+---
+name: frontend-developer
+description: >
+  Starter frontend developer agent — UI implementation, component structure,
+  accessibility, responsive layout, and visual polish. Edit for your project.
+---
+
+# frontend-developer
+
+Example agent shipped with `agentry`. Use it as a starting point and adapt it to your stack.
+
+## Focus
+
+- Implement and refine UI components and layouts.
+- Prioritize accessibility, responsive design, and visual polish.
+- Reuse existing design patterns and tokens before introducing new ones.
+- Keep changes small and verifiable; prefer the simplest approach that works.

package/examples/agents/frontend/frontend-developer/agentry.json

@@ -0,0 +1,5 @@
+{
+  "name": "frontend-developer",
+  "type": "agents",
+  "description": "Starter frontend developer agent persona."
+}

package/examples/rules/workflow/ask-dont-guess/RULE.md

@@ -0,0 +1,15 @@
+---
+name: ask-dont-guess
+description: >
+  Ask before guessing requirements or product truth. Act without asking only
+  when verified context already answers it. Prefer short, concrete questions.
+---
+
+# ask-dont-guess
+
+Before writing code, changing architecture, or stating product facts, ask when anything is unclear, ambiguous, missing, or a "probably fine" default that would lock the project in.
+
+- Use short, concrete questions; multiple-choice is fine.
+- Do not invent missing specs.
+- When verified project context already answers it, proceed — do not re-ask settled facts.
+- When docs and code conflict, trust verified code and runtime evidence.

package/examples/rules/workflow/ask-dont-guess/agentry.json

@@ -0,0 +1,5 @@
+{
+  "name": "ask-dont-guess",
+  "type": "rules",
+  "description": "Ask before guessing requirements or product truth."
+}

package/examples/scripts/env/doctor/agentry.json

@@ -0,0 +1,5 @@
+{
+  "name": "doctor",
+  "type": "scripts",
+  "description": "Print a simple environment readiness check."
+}

package/examples/scripts/env/doctor/run.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Starter script shipped with agentry. Prints a simple readiness check.
+set -euo pipefail
+echo "agentry: environment OK"

package/examples/skills/prompt/enhance-prompt/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: enhance-prompt
+description: >
+  Use when the user asks to enhance, improve, rewrite, optimize, or clarify a prompt —
+  or when always-on prompt enhancement is enabled for the session.
+  Rewrites casual or vague chat into precise, portable agent instructions
+  without injecting workspace paths, stack, or session-local context.
+  Preserves user-stated contracts; ranks related skills; asks clarifying /
+  mode / better-decision questions when needed; ends with an after-finish summary instruction.
+---
+
+# enhance-prompt
+
+Rewrite the user’s message into a precise, portable agent prompt. **Enhance = clarify and structure — never strip user-stated details that affect accuracy.** Accuracy first; tokens second (same or better meaning, fewer tokens).
+
+Do **not** invent requirements or paste workspace-local paths/stack. For shape and examples, open [references/TEMPLATE.md](references/TEMPLATE.md).
+
+## Procedure
+
+Apply passes in order. Deliver one copy-ready enhanced prompt (or questions-first when blocked — see pass 0).
+
+### 0) Clarify, suggest, choose mode (ask before guessing)
+
+Before (or instead of) emitting a full enhanced prompt, ask when it improves accuracy.
+
+**Ask when:**
+
+- Critical details are missing (fields, success criteria, scope, must-nots)
+- A better / more optimal decision exists than what the user stated — propose it; don’t silently override
+- Approach is ambiguous (how to do X vs Y given what they wrote)
+- Depth / packing mode is unclear for a large task
+
+**How to ask:**
+
+- Prefer short multiple-choice or yes/no + one-line rationale
+- Suggest **better options** (optimal defaults) labeled as suggestions — user can reject
+- Ask **mode** when useful: `compact` | `standard` | `full` (see Depth dial)
+- Ask approach forks only when they change the result (e.g. auth vs unauth OTP purpose)
+- Cap: **MAX 3 questions** per turn (batch them). Don’t interrogate for niceties.
+- If the user said “just enhance” / “don’t ask” / always-on with enough signal → enhance without questions
+- Casual but clear enough → enhance; put residual ambiguity under **Open questions** for the implementer
+
+**Question-first output** (when blocked on critical gaps):
+
+1. Brief “what I understood”
+2. Up to 3 questions (include mode / better-decision suggestions when relevant)
+3. Optional mini draft only if helpful — still no path/stack injection
+
+After answers (or if not blocked), continue passes 1–8.
+
+### Depth dial
+
+| Mode | When | Behavior |
+|------|------|----------|
+| `compact` | User asks, or rich contract already dense | Densest packing; full contracts kept; minimal Steps |
+| `standard` | Default | Normal sections; Steps only if needed |
+| `full` | Large / multi-system task, or user asks | More Steps + verify detail; still no path/stack dumps |
+
+Same accuracy floor in all modes — only verbosity changes. If unset, use `standard` (or ask once when the task is large and mode would matter).
+
+### 1) Full-text enhance
+
+- Fix grammar, wording, clarity; prefer precise verbs.
+- Remove filler, noise symbols, decorative separators, emojis.
+- Preserve user intent and constraints; never invent requirements, brand systems, stack, or scope the user did not ask for.
+- **Do not rename** user field names (`phone` stays `phone`, not `phone-number`).
+
+### 2) Context policy (non-negotiable)
+
+**Prompt context must be portable and session-safe.**
+
+#### Always preserve (if present in the user input)
+
+Contracts — compressing them away makes results worse:
+
+- Endpoint lists, request/response bodies, field lists (e.g. `{ phone, password, code }`)
+- Remove / keep / replace lists
+- Security rules, do / don’t, acceptance criteria
+- Explicit open questions or ambiguities the user left unresolved
+- Any detail that changes implementation behavior
+
+**Enhance** = reorganize and tighten. **Not** = delete or “summarize away” those facts.
+
+**Rich input** → compress wording only; **copy contracts forward** (don’t rebuild from memory).  
+**Casual input** → add structure without inventing environment.
+
+#### Never inject
+
+- Absolute or relative project/workspace folder paths
+- Repo roots, home paths, machine-specific paths
+- Tech stack / framework / language lists the target workspace already provides via `AGENTS.md`, `context/`, rules, or open files
+- Long dumps of docs already loadable in the *target* workspace
+- Paths or facts from the *current* workspace when the prompt will be used elsewhere
+- Invented field names, status codes, or API shapes the user did not state
+- Silent “optimal” overrides the user didn’t accept (suggest via pass 0 instead)
+
+Rules of thumb:
+
+- Agent can read it from the target workspace → don’t paste paths/stack/docs.
+- User stated a contract → keep it densely (tables / one-liners OK).
+- Unsure if session-local → omit or `[use target workspace context]`.
+
+### 3) Structure / layout enhance
+
+Use only sections with content; drop empty ones. One structure. **One home per fact** (Contract = shapes; Constraints = must-not; Steps = order only).
+
+- **Title** — when helpful
+- **Goal** — success looks like
+- **Contract** (optional) — APIs / bodies / remove-keep; prefer compact packing
+- **Constraints** — must / must-not
+- **Steps** — only if order matters (omit in `compact` unless essential)
+- **Related skills** — pass 5
+- **Output** — deliverable format
+- **Open questions** — unresolved; “resolve from workspace — don’t guess”
+- **After you finish** — pass 6
+
+After drafting: **Goal ↔ Contract ↔ Constraints ↔ Steps must agree**.
+
+### 4) Token optimization + dedup
+
+- Same or better meaning, fewer tokens — **without dropping preserved contracts**.
+- Strip banners, redundant headers, fluff verbs.
+- Prefer short imperatives; pack field lists and endpoints as compact lines/tables.
+- **Dedup:** remove the same constraint repeated across Goal / Constraints / Steps; delete Steps that only restate Contract.
+
+### 5) Related skills (precision)
+
+Discover skills relevant to the prompt; attach **inside** the prompt.
+
+1. Search installed / project / agent skills (`npx skills list`, `AGENTS.md`, agent skills dirs). Prefer **target** environment.
+2. Rank by relevance to the goal; keep the **strongest** matches only (prefer ≤5).
+3. Each entry: name + one “use for …” tied to the goal. Optional: mark top 1–2 as “load first”.
+4. Skip weak / unrelated. Do not invent skill names.
+5. If none: omit section or `None found — proceed with workspace defaults.`
+
+### 6) After you finish (handoff summary instruction)
+
+End with **After you finish**: tell the *implementing* agent, once work is done, write a result summary that:
+
+- Anyone can understand (plain language)
+- Still detailed — what changed, added/removed, how to verify, what’s still open
+- Is **not** a prompt restatement or enhancer changelog
+
+Always include unless the user asked to omit post-work summaries.
+
+### 7) Ambiguity policy
+
+- Unclear but non-blocking → **Open questions** for the implementer; do not invent a default.
+- Blocking → return to pass 0 (ask). Never silently pick auth rules, field names, or modes the user didn’t state or accept.
+
+### 8) Fidelity checklist + silent self-eval (before emit)
+
+**Must pass before delivering the enhanced prompt:**
+
+- [ ] Every user field / body / endpoint preserved?
+- [ ] Every remove / keep preserved?
+- [ ] Goal ↔ Contract ↔ Steps agree?
+- [ ] No renamed fields; no invented stack / paths?
+- [ ] No silent override of user intent (suggestions only via asks)?
+- [ ] Deduped; depth mode respected?
+
+If any fail → fix once, then emit.
+
+Silently score 1–5: fidelity, portability, density. If fidelity < 5 → revise once. Don’t print scores unless asked.
+
+Optional chat-only enhancer changelog after the copy-ready block — omit if overloaded or user disabled it.
+
+## Always-on mode
+
+If the user asks to enhance every chat / every prompt:
+
+1. Create or update `AGENTS.md` in the **target** project.
+2. Add a **Skills** section: when-to-use vs always-use.
+3. Register `enhance-prompt` as always-on, e.g.:
+
+```yaml
+alwaysApply: true
+```
+
+Always-on: rewrite the user message into a better agent prompt **before** acting — still obey context policy and fidelity rules. Prefer enhancing over asking unless blocked on critical gaps (then ≤3 tight questions).
+
+## Output
+
+1. Either questions-first (pass 0) **or** one copy-ready enhanced prompt (Related skills when found + **After you finish**).
+2. Optional brief chat-only enhancer changelog outside that block.
+3. Do not announce skill usage unless the user asks.

package/examples/skills/prompt/enhance-prompt/references/TEMPLATE.md

@@ -0,0 +1,182 @@
+# enhance-prompt — output template
+
+Enhance = clarify + structure. **Never strip user-stated contracts.** Never inject paths/stack. Ask (≤3) when blocked or when a better decision/mode would help — don’t silently override.
+
+## Correct output shape
+
+```markdown
+# <short title>
+
+## Goal
+<what success looks like>
+
+## Contract
+<optional — compact endpoint/body/remove-keep lines the user stated>
+
+## Constraints
+- <must / must-not — one home; don’t repeat Contract>
+
+## Steps
+1. <only if order matters>
+2. …
+
+## Related skills
+- `/skill-name` *(load first)* — use for <why tied to goal>
+- `/other` — use for <why>
+
+## Output
+<deliverable format>
+
+## Open questions
+- <resolve from workspace — don’t guess>
+
+## After you finish
+When the work is done, write a summary anyone can understand, while remaining detailed:
+- What changed (added/removed)
+- How to verify
+- Anything still open or risky
+```
+
+Omit empty sections. Respect depth dial: `compact` | `standard` | `full`.
+
+---
+
+## Questions-first shape (pass 0)
+
+When critical gaps or better decisions/modes matter:
+
+```markdown
+## Understood
+<1–3 lines of intent>
+
+## Questions (max 3)
+1. **Mode:** run `compact` (densest), `standard` (default), or `full` (more steps/verify)? — suggestion: `standard` because <why>
+2. **Better decision:** you asked for X; Y is often safer/cleaner because <why>. Use **Y** or keep **X**?
+3. **Missing detail:** <field / success criteria / scope> — options A / B / C?
+
+Reply with choices; then I’ll emit the full enhanced prompt.
+```
+
+Do not invent stack/paths in questions. Don’t ask if the user said not to, or signal is already enough.
+
+---
+
+## Example A — casual UI (standard)
+
+**In:** `Hey bro, the frontend look mid can you improve it?`
+
+**Out (right):**
+
+```markdown
+# Improve frontend UI quality
+
+## Goal
+Raise frontend visual quality so the first viewport and overall UI feel polished and intentional.
+
+## Constraints
+- Preserve existing behavior/content unless change is required for the visual fix
+- Do not invent brand, stack, or design language
+- Prefer target workspace design patterns when present
+- First viewport: brand signal, one headline, short support, CTA group, one dominant visual
+
+## Related skills
+- `/frontend-design` *(load first)* — layout and visual polish (if installed)
+
+## Output
+UI improvements in the target workspace.
+
+## After you finish
+Plain-language summary anyone can follow: what looked weak, what changed, how to check desktop and mobile.
+```
+
+**Wrong:** invent React/Tailwind paths under `/Users/...`.
+
+---
+
+## Example B — ask mode + better decision (before enhance)
+
+**In:** `refactor auth otp stuff, make it better`
+
+**Questions-first (right):**
+
+```markdown
+## Understood
+You want an auth/OTP refactor toward a cleaner flow, but the target shape isn’t specified.
+
+## Questions (max 3)
+1. **Mode:** `compact`, `standard`, or `full`? — suggestion: `full` (multi-endpoint refactor).
+2. **Better decision:** collapse to `otp/request` → action endpoints (login | register | password-change) with OTP verified **inside** actions (no public verify)? Or keep a public verify step?
+3. **Register body:** if OTP is inside register, should the body be `{ phone, password, code }` (recommended) or something else you already use?
+
+Reply 1–3; then I’ll emit the enhanced prompt with contracts preserved.
+```
+
+**Wrong:** silently invent full API + FastAPI stack + `G:\Projects\...` without asking.
+
+---
+
+## Example C — rich auth: preserve contracts (compact packing)
+
+**In (excerpt):** OTP verify internal; `otp/request` → action; register `{ phone, password, code }`; password-change like login + `new_password`; remove public verify + change/reset.
+
+**Wrong (diluted):**
+
+```markdown
+## Constraints
+- Register: accept phone-number and password only
+```
+
+**Right (`compact` / `standard`):**
+
+```markdown
+# Auth: OTP internal + collapse password APIs
+
+## Goal
+OTP verification is internal only. Public flow: otp/request → action (`login` | `register` | `password-change`). Remove public verify-OTP and separate change/reset password APIs.
+
+## Contract
+- `POST /auth/otp/request` — `{ phone, purpose }`
+- `POST /auth/login` — `{ phone, method, secret }`
+- `POST /auth/register` — `{ phone, password, code }`  ← OTP inside register
+- `POST /auth/password-change` — `{ phone, method, secret, new_password }`
+- Keep: refresh, logout
+- Remove: public verify-OTP; password change; password reset; otp_proof cookie register flow if present
+
+## Constraints
+- Verify-OTP stays internal — do not re-expose
+- Register: no `method`, no `secret`
+- `locale_pref`: prefer `localStorage`, else cookies
+- No invented auth fields/status/error shapes; use target workspace
+- Preserve existing security behavior unless user said otherwise
+- No path/stack paste — load from target workspace
+
+## Related skills
+- Rank ≤5 installed skills for auth / API / frontend / tests; mark top as load first
+
+## Output
+Backend + frontend matching Contract.
+
+## Open questions
+- Authenticated vs unauthenticated password-change: resolve OTP purpose / phone-vs-session from workspace — don’t guess
+
+## After you finish
+Plain + detailed summary: before→after flow, endpoints removed vs added (with shapes), how to verify (tests + results), anything still open.
+```
+
+---
+
+## Example D — path / stack leak anti-pattern
+
+**Wrong:** `/home/ubuntu/...`, `/Users/dev/...`, “Stack: Next.js, Prisma…”, README dumps.
+
+**Right:** portable Goal/Contract/Constraints; `[use target workspace context]` if a pointer is needed.
+
+---
+
+## Fidelity gate (before emit)
+
+- Fields/endpoints/remove-keep all present?
+- No renames (`phone` not `phone-number`)?
+- Goal ↔ Contract ↔ Steps agree?
+- No silent override (suggestions only via questions)?
+- Deduped; mode respected?

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mhmdreza-rafiei/agentry",
+  "version": "0.1.0",
+  "description": "One CLI to install agents, skills, rules, and scripts into any project or globally — portable AI/agent tooling.",
+  "bin": {
+    "agentry": "bin/agentry.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "profile",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "agentry": "node bin/agentry.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "skills",
+    "rules",
+    "cli",
+    "cursor",
+    "agentic",
+    "scaffold"
+  ],
+  "license": "MIT"
+}

package/profile/backend.json

@@ -0,0 +1,5 @@
+{
+  "skills": ["prompt/enhance-prompt"],
+  "rules": ["workflow"],
+  "scripts": ["env/doctor"]
+}

package/profile/frontend.json

@@ -0,0 +1,5 @@
+{
+  "agents": ["frontend"],
+  "skills": ["prompt/enhance-prompt"],
+  "rules": ["workflow/ask-dont-guess"]
+}

package/src/commands.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Assets install under `<root>/.cursor/<type>/<category>/<name>`.
+// ponytail: single target dir (.cursor) for now; per-agent targets (.claude, .codex)
+// can be added later via a `target` field in each asset's agentry.json.
+function targetRoot({ global: isGlobal, dir } = {}) {
+  const base = isGlobal ? os.homedir() : dir || process.cwd();
+  return path.join(base, '.cursor');
+}
+
+function lockPath(root) {
+  return path.join(root, 'agentry.lock.json');
+}
+
+function readLock(root) {
+  try {
+    return JSON.parse(fs.readFileSync(lockPath(root), 'utf8'));
+  } catch {
+    return { version: 1, items: {} };
+  }
+}
+
+function writeLock(root, lock) {
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(lockPath(root), JSON.stringify(lock, null, 2) + '\n');
+}
+
+function installOne(asset, opts) {
+  const root = targetRoot(opts);
+  const dest = path.join(root, asset.type, asset.id);
+  fs.rmSync(dest, { recursive: true, force: true }); // idempotent re-install
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.cpSync(asset.dir, dest, { recursive: true });
+  const lock = readLock(root);
+  lock.items[`${asset.type}/${asset.id}`] = { installedAt: new Date().toISOString() };
+  writeLock(root, lock);
+  return dest;
+}
+
+// Removes a type, a category, or a single asset from the install target.
+// selector: undefined -> whole type; "category" -> category; "category/name" -> one asset.
+function removeSelection(type, selector, opts) {
+  const root = targetRoot(opts);
+  const rel = [type, selector].filter(Boolean).join('/');
+  const dest = path.join(root, rel);
+  const existed = fs.existsSync(dest);
+  fs.rmSync(dest, { recursive: true, force: true });
+  const lock = readLock(root);
+  const removedKeys = [];
+  for (const key of Object.keys(lock.items)) {
+    if (key === rel || key.startsWith(rel + '/')) {
+      delete lock.items[key];
+      removedKeys.push(key);
+    }
+  }
+  writeLock(root, lock);
+  return { existed, removedKeys };
+}
+
+module.exports = { targetRoot, lockPath, readLock, installOne, removeSelection };

package/src/profile.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Profiles are plain JSON under `<baseDir>/profile/<name>.json`, mapping each
+// asset type to a list of selectors, e.g.:
+//   { "repo": "author/repo", "skills": ["prompt/enhance-prompt"], "rules": ["workflow"] }
+// `repo` is optional; the command-line source (when given) takes precedence.
+function loadProfile(name, baseDir) {
+  const file = path.join(baseDir || process.cwd(), 'profile', `${name}.json`);
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    throw new Error(`Profile not found or invalid JSON: ${file}`);
+  }
+  return { file, cfg };
+}
+
+module.exports = { loadProfile };

package/src/registry.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Discovers assets inside a *source root* (a fetched repo or local path).
+// Two discovery modes, unioned:
+//   1) Under <type>/ :   <type>/<name>/  or  <type>/<category>/<name>/
+//   2) At the repo root (like `npx skills add`), classified by a marker file:
+//        <name>/SKILL.md            -> skills/<name>
+//        <group>/<name>/SKILL.md    -> skills/<group>/<name>
+//      (AGENT.md -> agents, RULE.md -> rules). Scripts have no root marker.
+const TYPES = ['agents', 'skills', 'rules', 'scripts'];
+const MARKERS = { skills: 'SKILL.md', agents: 'AGENT.md', rules: 'RULE.md', scripts: null };
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function entries(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function hasFile(dir) {
+  return entries(dir).some((e) => e.isFile());
+}
+
+function firstHeading(md) {
+  const m = md.match(/^#\s+(.+)$/m);
+  return m ? m[1].trim() : '';
+}
+
+function frontmatterDescription(md) {
+  const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return '';
+  const lines = fm[1].split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const dm = lines[i].match(/^description:\s*(.*)$/);
+    if (!dm) continue;
+    let val = dm[1].trim();
+    if (val === '' || val === '>' || val === '|' || val === '>-' || val === '|-') {
+      const collected = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        if (/^\s+\S/.test(lines[j])) collected.push(lines[j].trim());
+        else break;
+      }
+      val = collected.join(' ');
+    }
+    return val.trim();
+  }
+  return '';
+}
+
+function assetDescription(dir) {
+  const cfg = readJson(path.join(dir, 'agentry.json'));
+  if (cfg && cfg.description) return cfg.description;
+  for (const f of ['SKILL.md', 'AGENT.md', 'RULE.md', 'README.md']) {
+    const p = path.join(dir, f);
+    if (!fs.existsSync(p)) continue;
+    const md = fs.readFileSync(p, 'utf8');
+    const d = frontmatterDescription(md) || firstHeading(md);
+    if (d) return d;
+  }
+  return '';
+}
+
+function hasMarker(dir, marker) {
+  return !!marker && fs.existsSync(path.join(dir, marker));
+}
+
+function makeAsset(type, category, name, dir) {
+  const id = category ? `${category}/${name}` : name;
+  return { type, category, name, id, dir, description: assetDescription(dir) };
+}
+
+// Assets living under an explicit <type>/ folder (this repo's own convention).
+function collectFromTypeDir(base, type, out) {
+  for (const child of entries(base)) {
+    if (!child.isDirectory()) continue;
+    const childDir = path.join(base, child.name);
+    if (hasFile(childDir)) {
+      out.push(makeAsset(type, null, child.name, childDir));
+    } else {
+      for (const item of entries(childDir)) {
+        if (!item.isDirectory()) continue;
+        out.push(makeAsset(type, child.name, item.name, path.join(childDir, item.name)));
+      }
+    }
+  }
+}
+
+// Assets at the repo root, identified by marker file (e.g. SKILL.md).
+function collectFromRoot(root, type, marker, out) {
+  if (!marker) return;
+  for (const child of entries(root)) {
+    if (!child.isDirectory()) continue;
+    if (child.name.startsWith('.') || child.name === 'node_modules' || TYPES.includes(child.name)) continue;
+    const childDir = path.join(root, child.name);
+    if (hasMarker(childDir, marker)) {
+      out.push(makeAsset(type, null, child.name, childDir));
+    } else {
+      for (const item of entries(childDir)) {
+        if (item.isDirectory() && hasMarker(path.join(childDir, item.name), marker)) {
+          out.push(makeAsset(type, child.name, item.name, path.join(childDir, item.name)));
+        }
+      }
+    }
+  }
+}
+
+function listType(root, type) {
+  const out = [];
+  const base = path.join(root, type);
+  if (fs.existsSync(base)) collectFromTypeDir(base, type, out);
+  collectFromRoot(root, type, MARKERS[type], out);
+  const seen = new Set();
+  return out
+    .filter((a) => (seen.has(a.id) ? false : seen.add(a.id)))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function allAssets(root) {
+  return TYPES.flatMap((t) => listType(root, t));
+}
+
+// selector: undefined -> whole type; "category/name" -> one asset;
+// "category" -> whole category; bare name -> fallback exact-name match.
+function select(root, type, selector) {
+  const items = listType(root, type);
+  if (!selector) return items;
+  if (selector.includes('/')) return items.filter((a) => a.id === selector);
+  const byCategory = items.filter((a) => a.category === selector);
+  if (byCategory.length) return byCategory;
+  return items.filter((a) => a.name === selector);
+}
+
+module.exports = { TYPES, listType, allAssets, select };

package/src/source.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+function isLocalPath(source) {
+  return (
+    source.startsWith('.') ||
+    source.startsWith('/') ||
+    source.startsWith('~') ||
+    fs.existsSync(source)
+  );
+}
+
+// Accepts a full git URL or the "author/repo" GitHub shorthand.
+function toGitUrl(source) {
+  if (/^https?:\/\//.test(source) || source.startsWith('git@')) return source;
+  if (/^[\w.-]+\/[\w.-]+$/.test(source)) return `https://github.com/${source}.git`;
+  return null;
+}
+
+// Resolves a source (local path | author/repo | git URL) to a local root.
+// Remote sources are shallow-cloned to a temp dir; call cleanup() when done.
+function resolveSource(source) {
+  if (isLocalPath(source)) {
+    const root = path.resolve(source.replace(/^~/, os.homedir()));
+    if (!fs.existsSync(root)) throw new Error(`Path not found: ${source}`);
+    return { root, cleanup() {} };
+  }
+  const url = toGitUrl(source);
+  if (!url) throw new Error(`Cannot resolve source "${source}". Use a local path, author/repo, or git URL.`);
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agentry-src-'));
+  try {
+    execFileSync('git', ['clone', '--depth', '1', '--quiet', url, tmp], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+  } catch (e) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    const detail = e.stderr ? e.stderr.toString().trim() : e.message;
+    throw new Error(`git clone failed for ${url}\n${detail}`);
+  }
+  return {
+    root: tmp,
+    cleanup() {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    },
+  };
+}
+
+module.exports = { isLocalPath, toGitUrl, resolveSource };