developer-agent-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Skills Pack 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,127 @@
+# Developer Agent Skills 🤖⚡
+
+A production-ready collection of essential **AI Agent Skills** for software developers and web engineering workflows, designed for dual consumption:
+1. **As an AI Skills repository** using `npx skills add AdnanIqbalKhan/developer-agent-skills` (Claude Code, Cursor, Antigravity, GitHub Copilot, Codex, etc.).
+2. **As an NPM package & CLI** via `npm install developer-agent-skills` or `npx developer-agent-skills`.
+
+---
+
+## ⚡ Option 1: Install via AI Skills CLI (`npx skills add`)
+
+To install skills directly into your project's AI agent environment using the standard `skills` CLI:
+
+```bash
+# Add all skills from this repository to your project
+npx skills add AdnanIqbalKhan/developer-agent-skills
+
+# Add a specific skill from this repository
+npx skills add AdnanIqbalKhan/developer-agent-skills/code-review
+npx skills add AdnanIqbalKhan/developer-agent-skills/figma
+npx skills add AdnanIqbalKhan/developer-agent-skills/git-branch-report
+npx skills add AdnanIqbalKhan/developer-agent-skills/project-docs-sync
+npx skills add AdnanIqbalKhan/developer-agent-skills/ui-visual-feedback-loop
+```
+
+---
+
+## 📦 Option 2: Install via NPM Package & CLI (`npx developer-agent-skills`)
+
+### Via `npx` (No installation needed):
+
+```bash
+# List all bundled skills
+npx developer-agent-skills list
+
+# Install skills into default project folder (.agents/skills)
+npx developer-agent-skills install
+
+# Install skills for specific agent targets
+npx developer-agent-skills install --agent claude      # installs into .claude/skills
+npx developer-agent-skills install --agent cursor      # installs into .cursor/skills
+npx developer-agent-skills install --agent codex       # installs into .codex/skills
+npx developer-agent-skills install --agent antigravity # installs into .gemini/skills
+
+# Install specific skills only
+npx developer-agent-skills install --skills code-review,git-branch-report
+```
+
+*Binary aliases available*: `npx developer-agent-skills`, `npx developer-skills`, `npx agent-skills`, `npx skills-pack`.
+
+### Via NPM Dependency:
+
+```bash
+npm install developer-agent-skills
+```
+
+```javascript
+const { getSkills, getSkillPath, installSkills } = require('developer-agent-skills');
+
+// Programmatically discover or copy skills
+const skills = getSkills();
+installSkills({ targetDir: './.agents/skills' });
+```
+
+---
+
+## 🛠 Included Skills Catalog
+
+| Skill Name | Description | Location |
+| :--- | :--- | :--- |
+| **`code-review`** | Audits code changes from Git ranges or ticket branches and produces priority-sorted review reports. | `skills/code-review/SKILL.md` |
+| **`figma`** | Inspects Figma URLs directly in Chrome DevTools MCP, extracting layout/tokens without API quota limits. | `skills/figma/SKILL.md` |
+| **`git-branch-report`** | Generates detailed Markdown diff reports for any Git branch compared with a base branch. | `skills/git-branch-report/SKILL.md` |
+| **`project-docs-sync`** | Audits and synchronizes whole-project documentation with the live codebase. | `skills/project-docs-sync/SKILL.md` |
+| **`ui-visual-feedback-loop`** | Unified visual verification loop using Chrome DevTools MCP or automated Playwright screenshot diffing. | `skills/ui-visual-feedback-loop/SKILL.md` |
+
+---
+
+## 📂 Repository Structure
+
+```text
+developer-agent-skills/
+├── bin/
+│   └── cli.js                      # Executable CLI tool for npx developer-agent-skills
+├── skills/                          # Root skills directory for npx skills add
+│   ├── code-review/                # Skill folder
+│   │   ├── SKILL.md                # Standard YAML frontmatter + instructions
+│   │   ├── references/
+│   │   └── scripts/
+│   ├── figma/
+│   │   ├── SKILL.md
+│   │   └── references/
+│   ├── git-branch-report/
+│   │   ├── SKILL.md
+│   │   └── scripts/
+│   ├── project-docs-sync/
+│   │   ├── SKILL.md
+│   │   └── scripts/
+│   └── ui-visual-feedback-loop/
+│       ├── SKILL.md
+│       ├── references/
+│       └── scripts/
+├── index.js                         # Dynamic Node.js module API
+├── package.json                     # NPM manifest & bin declarations
+├── LICENSE                          # MIT License
+└── README.md                        # Documentation
+```
+
+---
+
+## 🚢 Publishing to NPM
+
+```bash
+# Verify package tarball
+npm pack --dry-run
+
+# Test publish payload
+npm publish --dry-run
+
+# Publish to NPM registry
+npm publish --access public
+```
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © Developer Agent Skills Contributors

package/bin/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const { getSkills, installSkills } = require('../index');
+
+const args = process.argv.slice(2);
+const command = args[0] || 'help';
+
+function printHelp() {
+  console.log(`
+🤖 Developer AI Agent Skills CLI
+
+Usage:
+  npx developer-agent-skills <command> [options]
+  npx developer-skills <command> [options]
+  npx agent-skills <command> [options]
+
+Commands:
+  list                       List all packaged skills and their descriptions
+  install [target-dir]       Install skills into a project directory (default: .agents/skills)
+  export <target-dir>        Export skills folder to a target directory
+  help                       Show this help message
+
+Options:
+  --agent <agent-type>       Preset directory for specific agents:
+                             claude      -> .claude/skills
+                             codex       -> .codex/skills
+                             cursor      -> .cursor/skills
+                             antigravity -> .gemini/skills
+                             all         -> .agents/skills (default)
+  --skills <name1,name2>     Comma-separated list of specific skills to install
+
+Examples:
+  npx developer-agent-skills list
+  npx developer-skills install
+  npx developer-skills install --agent claude
+  npx agent-skills install ./custom-skills-dir
+`);
+}
+
+function parseFlags(argsList) {
+  const flags = { agent: null, skills: null, positional: [] };
+  for (let i = 0; i < argsList.length; i++) {
+    const arg = argsList[i];
+    if (arg === '--agent' && i + 1 < argsList.length) {
+      flags.agent = argsList[++i];
+    } else if (arg === '--skills' && i + 1 < argsList.length) {
+      flags.skills = argsList[++i].split(',').map(s => s.trim());
+    } else if (!arg.startsWith('--')) {
+      flags.positional.push(arg);
+    }
+  }
+  return flags;
+}
+
+function resolveAgentTargetDir(agentType, userProvidedDir) {
+  if (userProvidedDir) return userProvidedDir;
+  switch (agentType?.toLowerCase()) {
+    case 'claude': return '.claude/skills';
+    case 'codex': return '.codex/skills';
+    case 'cursor': return '.cursor/skills';
+    case 'antigravity': return '.gemini/skills';
+    default: return '.agents/skills';
+  }
+}
+
+switch (command) {
+  case 'list': {
+    console.log('\n📦 Available Developer AI Agent Skills:\n');
+    const skills = getSkills();
+    skills.forEach((skill, index) => {
+      console.log(`  ${index + 1}. \x1b[36m${skill.name}\x1b[0m`);
+      console.log(`     ${skill.description}`);
+      console.log(`     \x1b[90mPath: ${skill.dir}\x1b[0m\n`);
+    });
+    break;
+  }
+
+  case 'install':
+  case 'export': {
+    const flags = parseFlags(args.slice(1));
+    const rawTarget = flags.positional[0];
+    const targetDir = resolveAgentTargetDir(flags.agent, rawTarget);
+    
+    console.log(`\n🚀 Installing skills into \x1b[34m${targetDir}\x1b[0m...`);
+    const result = installSkills({
+      targetDir,
+      skills: flags.skills
+    });
+
+    console.log(`\x1b[32m✔ Successfully installed ${result.installed.length} skills:\x1b[0m`);
+    result.installed.forEach(name => console.log(`   - ${name}`));
+    console.log(`\n📍 Location: ${result.targetDir}\n`);
+    break;
+  }
+
+  case 'help':
+  case '--help':
+  case '-h':
+  default:
+    printHelp();
+    break;
+}

package/index.js

@@ -0,0 +1,119 @@
+const fs = require('fs');
+const path = require('path');
+
+const SKILLS_DIR = path.join(__dirname, 'skills');
+
+/**
+ * Parse simple YAML frontmatter from SKILL.md
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const frontmatter = {};
+  const lines = match[1].split('\n');
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      let value = line.slice(colonIdx + 1).trim();
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      frontmatter[key] = value;
+    }
+  }
+  return frontmatter;
+}
+
+/**
+ * Get list of available skills dynamically from the skills/ directory.
+ */
+function getSkills() {
+  if (!fs.existsSync(SKILLS_DIR)) return [];
+  const entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+  const skills = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const dirName = entry.name;
+      const skillPath = path.join(SKILLS_DIR, dirName);
+      const skillFilePath = path.join(skillPath, 'SKILL.md');
+      
+      let name = dirName;
+      let description = '';
+
+      if (fs.existsSync(skillFilePath)) {
+        const content = fs.readFileSync(skillFilePath, 'utf8');
+        const fm = parseFrontmatter(content);
+        if (fm.name) name = fm.name;
+        if (fm.description) description = fm.description;
+      }
+
+      skills.push({
+        name,
+        description,
+        dir: `skills/${dirName}`,
+        path: skillPath,
+        skillFilePath
+      });
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Get path of a specific skill by name.
+ */
+function getSkillPath(skillName) {
+  const available = getSkills();
+  const found = available.find(s => s.name === skillName);
+  return found ? found.path : null;
+}
+
+/**
+ * Copy directory recursively.
+ */
+function copyDirSync(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Install bundled skills into target directory.
+ */
+function installSkills({ targetDir, skills, overwrite = true }) {
+  const resolvedTarget = path.resolve(targetDir);
+  const available = getSkills();
+  const toInstall = skills 
+    ? available.filter(s => skills.includes(s.name))
+    : available;
+
+  const installed = [];
+  for (const skill of toInstall) {
+    const destSkillDir = path.join(resolvedTarget, skill.name);
+    if (fs.existsSync(destSkillDir) && !overwrite) {
+      continue;
+    }
+    copyDirSync(skill.path, destSkillDir);
+    installed.push(skill.name);
+  }
+  return { installed, targetDir: resolvedTarget };
+}
+
+module.exports = {
+  getSkills,
+  getSkillPath,
+  installSkills
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "developer-agent-skills",
+  "version": "1.0.0",
+  "description": "Essential AI Agent Skills for software developers and web engineering workflows: code review, UI visual feedback loops, Figma DevTools inspection, git branch reporting, and project docs sync.",
+  "main": "index.js",
+  "bin": {
+    "developer-agent-skills": "bin/cli.js",
+    "developer-skills": "bin/cli.js",
+    "agent-skills": "bin/cli.js",
+    "skills-pack": "bin/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AdnanIqbalKhan/developer-agent-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AdnanIqbalKhan/developer-agent-skills/issues"
+  },
+  "homepage": "https://github.com/AdnanIqbalKhan/developer-agent-skills#readme",
+  "keywords": [
+    "developer-agent-skills",
+    "developer-skills",
+    "agent-skills",
+    "skills",
+    "ai-agent",
+    "claude-code",
+    "antigravity",
+    "cursor",
+    "codex",
+    "copilot",
+    "code-review",
+    "figma",
+    "ui-feedback"
+  ],
+  "license": "MIT",
+  "files": [
+    "bin",
+    "index.js",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node bin/cli.js list",
+    "list": "node bin/cli.js list",
+    "install-skills": "node bin/cli.js install"
+  }
+}

package/skills/code-review/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: code-review
+description: Review code changes from explicit commit SHAs/ranges or from the current Git branch by selecting commits whose subjects start with the branch-derived ticket name, ignoring branch version suffixes such as v2/v3. Use when Codex is asked to perform a code review, review branch commits, review a ticket branch, audit changed code, or create a priority-sorted issue report from commits.
+---
+
+# Code Review
+
+## Overview
+
+Produce an actionable code-review report for a Git branch or explicit commit target. Default to reviewing only commits in the current branch whose commit subject starts with the branch-derived ticket name; if the user provides commit SHAs or a Git range, review exactly that target instead.
+
+## Target Selection
+
+1. If the user supplies one or more commit SHAs, refs, or ranges, use those exactly and skip branch-name filtering.
+2. Otherwise, derive the ticket prefix from the current branch:
+   - Split branch names on `/` and inspect segments from right to left.
+   - Ignore version-only segments like `v2`, `v3`, `v10`.
+   - Strip trailing version suffixes like `-v2`, `_v3`, `.v4`.
+   - Prefer a ticket-like token such as `ABC-123` when present; otherwise use the cleaned branch segment.
+3. Select commits reachable from `HEAD` but not the target base branch whose subject starts with the ticket prefix. If the branch tracks its own remote counterpart, do not use that upstream as the base; fall back to `origin/main`, `origin/master`, `origin/develop`, `main`, `master`, or `develop`, or use the user-provided `--base`. Match case-insensitively.
+4. If no matching commits are found, do not silently broaden scope. Report the derived ticket prefix and ask for an explicit commit/range or base branch.
+
+Use the bundled script to make this deterministic. It attempts `git pull --ff-only` before collecting context, skips the pull if the working tree is dirty, and records a warning if pull fails:
+
+```bash
+python scripts/collect_review_context.py --repo . --output /tmp/code-review-context.md
+```
+
+Examples:
+
+```bash
+# Review explicit commits/range supplied by the user
+python scripts/collect_review_context.py --repo . --commit abc123 --commit def456 --output /tmp/code-review-context.md
+python scripts/collect_review_context.py --repo . --range origin/main..HEAD --output /tmp/code-review-context.md
+
+# Review branch commits using a specific base when needed
+python scripts/collect_review_context.py --repo . --base origin/main --output /tmp/code-review-context.md
+
+# After user approves the filtered list, review a selected subset by 1-based index
+python scripts/collect_review_context.py --repo . --select 1 --output /tmp/code-review-context.md
+python scripts/collect_review_context.py --repo . --select 2-6 --output /tmp/code-review-context.md
+```
+
+## Review Workflow
+
+1. Run `collect_review_context.py` from the repository root with `--no-diff` to produce the filtered commit list first. Let it try `git pull --ff-only` before collecting context. If pull fails or is skipped, continue and note the warning when asking for approval. Pass explicit commits/ranges when the user provided them.
+2. Show the filtered commits to the user and ask which commits to review before reading diffs or writing the report. Do not proceed until the user approves a selection. Accept `all`, one number such as `1`, a comma list such as `1,3,5`, or an inclusive range such as `2-6`.
+3. Run `collect_review_context.py` again with the approved selection, e.g. `--select all`, `--select 1`, or `--select 2-6`, and without `--no-diff` unless the user only wants the commit list.
+4. Read the generated context file, then inspect changed files directly as needed with `git show`, `git diff`, `git blame`, and targeted source-file reads.
+5. Focus on changed behavior and changed interfaces. Verify claims against the diff and current codebase.
+6. Read `references/review-rubric.md` before writing the final report.
+7. Produce a report that first lists the selected commits, then lists issues sorted by priority from highest to lowest. Include only findings that are actionable and supported by changed code.
+
+## Report Format
+
+Use this structure:
+
+```markdown
+# Code Review Report
+
+## Scope
+- Branch: `<branch>`
+- Base: `<base or explicit target>`
+- Ticket prefix: `<derived prefix or n/a>`
+- Commits reviewed: `<count>`
+
+## Selected Commits
+| # | SHA | Subject |
+|---:|---|---|
+| 1 | `<short-sha>` | `<commit subject>` |
+
+## Summary
+<one short paragraph>
+
+## Issues
+### P0 Critical
+- None, or issue entries
+
+### P1 High
+- None, or issue entries
+
+### P2 Medium
+- None, or issue entries
+
+### P3 Low
+- None, or issue entries
+```
+
+Issue entries must include:
+
+```markdown
+- **[P1 High] Short title** — `path/to/file.ext:line` (`commit-sha`)
+  - **Problem:** What is wrong.
+  - **Impact:** Why it matters.
+  - **Recommendation:** Concrete fix direction.
+```
+
+Always include the `Selected Commits` table using the commits from the generated context. If there are no selected commits, write `No commits selected.` in that section.
+
+If there are no issues, say `No actionable issues found in the reviewed commits.`
+
+## Constraints
+
+- Do not modify repository files during the review unless the user explicitly asks for fixes. The only default exception is the preflight `git pull --ff-only` attempt; never create merge commits during this pull.
+- Do not review unrelated commits when branch filtering finds no ticket-prefixed commits; ask for an explicit target instead.
+- Do not include style-only nits unless they indicate a real defect or maintainability risk.
+- Keep report ordering strictly P0, P1, P2, P3.

package/skills/code-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Code Review"
+  short_description: "Review branch commits by priority"
+  default_prompt: "Use $code-review to review this branch and write a priority-sorted issue report."

package/skills/code-review/references/review-rubric.md

@@ -0,0 +1,38 @@
+# Review Rubric
+
+Load this before writing the final report.
+
+## Priority order
+
+- **P0 Critical**: Introduces a likely outage, data loss, security/privacy breach, payment/order corruption, authentication bypass, or broken build/runtime startup for a core path.
+- **P1 High**: Definite functional regression in a normal user/admin flow, incorrect persisted state, SSR/client crash, API contract break, broken navigation, or high-confidence performance issue with user-visible impact.
+- **P2 Medium**: Edge-case defect, incomplete error handling, race condition, accessibility regression with meaningful impact, maintainability issue likely to create bugs soon, or moderate performance degradation.
+- **P3 Low**: Minor correctness risk, confusing code path, small maintainability concern, or low-impact UX issue. Avoid noisy nit-only findings.
+
+## Finding quality bar
+
+Only include a finding when all are true:
+
+1. The issue is introduced or exposed by the reviewed commits.
+2. The report can point to a changed file and approximate line or hunk.
+3. The impact is concrete, not speculative.
+4. The recommendation is specific enough for an engineer to act on.
+
+## Review checklist
+
+Prioritize these areas while reading the diff:
+
+- Runtime crashes: null/undefined access, missing imports, wrong exports, bad async assumptions, SSR/browser API misuse.
+- Data correctness: wrong IDs, wrong filters, incorrect state transitions, stale caches, lost user input, incorrect totals/prices/availability.
+- API boundaries: request/response shape mismatches, unhandled non-2xx responses, missing loading/error states, backward-incompatible changes.
+- Security and privacy: exposed secrets, unsafe redirects, injection, auth/permission bypass, sensitive data leaks.
+- Routing and UX flows: broken links, forms that cannot submit, redirects to invalid routes, inaccessible controls that block completion.
+- Performance: repeated expensive work in render paths, unbounded fetches, large unnecessary payloads, avoidable re-renders in hot components.
+- Maintainability: duplicated branching that can diverge, fragile assumptions, dead paths in changed logic, unclear ownership of side effects.
+
+## Output discipline
+
+- Sort by P0, P1, P2, then P3.
+- Within each priority, list higher confidence and higher impact first.
+- Prefer fewer high-quality findings over broad commentary.
+- If no issues meet the bar, state that no actionable issues were found.