@djm204/agent-skills

Compatible with:

44 curated prompt packs that encode principal-level domain expertise for AI coding assistants. Install into Cursor, Claude Code, Gemini CLI, GitHub Copilot, or OpenAI Codex — or compose into LangChain, CrewAI, and OpenAI Agents SDK pipelines via adapter templates.

Disclaimer: This project is provided for educational and experimental purposes only. The author takes no responsibility for any actions, outputs, or consequences resulting from an LLM or AI assistant following these rules. Use at your own risk. Always review AI-generated code before deploying to production.

What This Is

• Tiered behavioral prompts — each skill has 3 standalone tiers (minimal ~700 tokens, standard ~2,800, comprehensive ~7,500) encoding how to think about a domain, not just what to do
• A CLI installer — copies rule files to the right locations for Cursor, Claude Code, Gemini CLI, GitHub Copilot, and OpenAI Codex, with smart merging and conflict detection
• Adapter templates — reformats prompts into framework-specific boilerplate for LangChain, CrewAI, and OpenAI Agents SDK
• MCP servers — 13 skills define tool schemas that can be served over MCP, making them callable by any MCP-compatible agent

What This Isn't (Yet)

• Not runtime agents — skills are static prompts injected into context windows, not executable code
• Not deep framework integrations — adapters produce formatted strings and code scaffolds, not framework plugins

Installation

No installation required. Run directly with npx:

npx @djm204/agent-skills [skill-name]

Or install globally:

npm install -g @djm204/agent-skills
agent-skills [skill-name]

How to Use

Install into Your IDE

Navigate to your project directory and run:

npx @djm204/agent-skills web-frontend

This installs rule files for all supported IDEs (Cursor, Claude Code, Gemini CLI, GitHub Copilot, OpenAI Codex):

• CLAUDE.md — Development guide for Claude Code and Cursor with Claude
• GEMINI.md — Development guide for Gemini CLI
• AGENTS.md — Development guide for OpenAI Codex
• .cursor/rules/ — Rule files for Cursor IDE (.mdc format)
• .github/copilot-instructions.md — Instructions for GitHub Copilot

Install Multiple Skills

Combine skills for projects that span multiple domains:

npx @djm204/agent-skills web-frontend web-backend

List All Available Skills

npx @djm204/agent-skills --list

Preview Before Installing (Dry Run)

See what files will be created without making changes:

npx @djm204/agent-skills web-frontend --dry-run

Update to Latest Rules

Re-run with @latest to get updated skills:

npx @djm204/agent-skills@latest web-frontend

Install for Specific IDE

By default, skills install for all supported IDEs. Use --ide to target specific tools:

# Install only for Cursor IDE
npx @djm204/agent-skills web-frontend --ide=cursor

# Install only for Claude Code
npx @djm204/agent-skills web-frontend --ide=claude

# Install only for GitHub Copilot
npx @djm204/agent-skills web-frontend --ide=codex

# Install for multiple IDEs
npx @djm204/agent-skills web-frontend --ide=cursor --ide=codex

Remove Specific Skills

# Remove a single skill
npx @djm204/agent-skills --remove web-frontend

# Remove multiple skills
npx @djm204/agent-skills --remove web-frontend web-backend

# Remove from specific IDE only
npx @djm204/agent-skills --remove web-frontend --ide=cursor

# Skip confirmation prompt
npx @djm204/agent-skills --remove web-frontend --yes

Reset (Remove Everything)

npx @djm204/agent-skills --reset
npx @djm204/agent-skills --reset --ide=cursor
npx @djm204/agent-skills --reset --yes
npx @djm204/agent-skills --reset --force

Skill Pack Adapter Mode

Skills can also be composed into AI agent frameworks using the --adapter flag. This outputs a prompt file optimized for the target framework instead of installing IDE rule files.

npx @djm204/agent-skills <skill-name> --adapter=<adapter> [--tier=<tier>] [--out=<dir>]

Adapters

| Adapter | Output | Use With | |---------|--------|----------| | raw | Plain markdown prompt | Any LLM, testing | | cursor | .cursor/rules/ MDC files | Cursor IDE | | claude-code | CLAUDE.md section | Claude Code | | gemini | GEMINI.md section | Gemini CLI | | copilot | .github/copilot-instructions.md section | GitHub Copilot | | codex | AGENTS.md + .agents/skills/<name>/SKILL.md | OpenAI Codex | | openai-agents | Python Agent(instructions=...) snippet | OpenAI Agents SDK | | langchain | Python SystemMessagePromptTemplate | LangChain | | crewai | Python Agent(backstory=..., goal=...) | CrewAI |

Note: Adapters produce formatted prompt strings and code scaffolds — not runtime framework plugins. Tool definitions in skill packs (tools/*.yaml) are interface contracts that describe what a tool would accept and return. Your application provides the implementation.

Prompt Tiers

Each skill has three standalone prompt tiers. Choose the tier that fits your context budget:

| Tier | Approx. Tokens | Content | |------|---------------|---------| | minimal | ~700 | Core behavioral rules and anti-patterns only | | standard | ~2,800 | Principles, patterns, and decision frameworks (default) | | comprehensive | ~7,500 | Full reference with code examples and tables |

Examples

# Get a raw markdown prompt for use in any LLM
npx @djm204/agent-skills golang-expert --adapter=raw

# Generate a LangChain agent with minimal token usage
npx @djm204/agent-skills python-expert --adapter=langchain --tier=minimal

# Generate a CrewAI agent config and write to ./agents/
npx @djm204/agent-skills strategic-negotiator --adapter=crewai --out=./agents

# Generate an OpenAI Agents SDK snippet
npx @djm204/agent-skills devops-sre --adapter=openai-agents --tier=standard

# Compose multiple skills together (comma-separated)
npx @djm204/agent-skills fullstack,testing --adapter=claude-code --tier=comprehensive

Preview Test Cases

Each skill includes behavioral test cases. Use --test to see them without calling an LLM:

npx @djm204/agent-skills --test strategic-negotiator
npx @djm204/agent-skills --test golang-expert

MCP Server Mode

Skills with tool definitions can be served as MCP (Model Context Protocol) servers, making their tools callable by any MCP-compatible agent.

# Start an MCP server for a skill
npx @djm204/agent-skills serve research-assistant

# With custom tool handler implementations
npx @djm204/agent-skills serve research-assistant --handler-dir=./my-handlers

# With a specific prompt tier
npx @djm204/agent-skills serve research-assistant --tier=comprehensive

How It Works

1. The server loads the skill's tool definitions from tools/*.yaml
2. Each tool is registered with the MCP SDK using Zod-validated schemas
3. Tool handlers are resolved by priority: built-in > user-provided > stub
4. Skill prompts are exposed as MCP resources at skill://<name>/prompt/<tier>

Tools without a real implementation return structured "not implemented" responses describing what the tool expects and returns — useful for development and testing.

MCP Client Configuration

Adapters automatically emit the correct MCP config. For example, after npx @djm204/agent-skills research --adapter=cursor, the generated .cursor/mcp.json includes:

{
  "mcpServers": {
    "agent-skills-research-assistant": {
      "command": "npx",
      "args": ["-y", "@djm204/agent-skills-serve", "research-assistant"]
    }
  }
}

Programmatic Usage

import { createMcpServer, loadSkill } from '@djm204/agent-skills/api';

const skill = await loadSkill('skills/research-assistant');
const { server } = await createMcpServer(skill, {
  builtinHandlers: {
    web_search: async (params) => ({
      content: [{ type: 'text', text: JSON.stringify(results) }],
    }),
  },
});

CLI Options

| Option | Description | |--------|-------------| | --ide=[name] | Target IDE: cursor, claude, or codex (can be used multiple times) | | --adapter=[name] | Adapter for skill pack mode: raw, cursor, claude-code, copilot, openai-agents, langchain, crewai, codex | | --tier=[tier] | Prompt tier: minimal, standard, comprehensive (default: standard) | | --test | Preview test cases for a skill without calling an LLM | | --skill-dir=[dir] | Path to a custom skills directory (default: built-in skills/) | | --out=[dir] | Output directory for adapter files (default: current directory) | | --list, -l | List all available skills | | --dry-run | Preview changes without writing files | | --force, -f | Overwrite/remove even if files were modified | | --remove | Remove specified skills | | --reset | Remove ALL installed content | | --yes, -y | Skip confirmation prompt (for --remove and --reset) | | --version, -v | Show version number | | serve <skill> | Start MCP server for a skill (requires tools) | | --handler-dir=<dir> | Directory of custom tool handler .js files (with serve) | | --help, -h | Show help message |

Shorthand Aliases

Use short names instead of full skill names. Run --list to see all aliases.

Languages

| Alias | Skill | |-------|-------| | js, ts, javascript, typescript | javascript-expert | | go, golang | golang-expert | | py, python | python-expert | | rs, rust | rust-expert | | ruby, rb | ruby-expert | | swift | swift-expert | | kotlin, kt | kotlin-expert | | java | java-expert | | cpp | cpp-expert | | csharp, cs | csharp-expert |

Engineering

| Alias | Skill | |-------|-------| | frontend, fe | web-frontend | | backend, api | web-backend | | devops, sre | devops-sre | | cli | cli-tools | | data, dataeng | data-engineering | | ml, ai | ml-ai | | qa | qa-engineering | | test | testing | | chain, web3 | blockchain | | platform, platform-eng | platform-engineering | | unity | unity-dev-expert | | security, sec, appsec | security-expert |

Professional

| Alias | Skill | |-------|-------| | docs | documentation | | grants | grant-writer | | exec, ea | executive-assistant | | knowledge | knowledge-synthesis | | research, researcher | research-assistant |

Business

| Alias | Skill | |-------|-------| | product | product-manager | | project | project-manager | | compliance, regulatory | regulatory-sentinel | | allocator, resources | resource-allocator | | market-intel | market-intelligence | | supplychain | supply-chain | | harmonizer | supply-chain-harmonizer | | negotiator | strategic-negotiator | | predictive | predictive-maintenance | | marketing | marketing-expert |

Creative

| Alias | Skill | |-------|-------| | ux, uxd, design, designer | ux-designer | | brand | brand-guardian | | social-media | social-media-expert | | content-creation | content-creation-expert |

Education & Agents

| Alias | Skill | |-------|-------| | teach, teacher | educator | | agent, utility | utility-agent |

Available Skills (45)

Engineering (14)

| Skill | Description | |-------|-------------| | blockchain | Smart contracts, DeFi protocols, and Web3 applications (Solidity, Foundry, Viem) | | cli-tools | Command-line applications and developer tools (Cobra, Commander, Click) | | data-engineering | Data platforms and pipelines (ETL, data modeling, data quality) | | devops-sre | DevOps and SRE practices (incident management, observability, SLOs, chaos engineering) | | fullstack | Full-stack web applications with shared types, API contracts, and E2E testing | | ml-ai | Machine learning and AI systems (model development, deployment, monitoring) | | mobile | Mobile applications (React Native, Flutter, native iOS/Android) | | platform-engineering | Internal developer platforms, infrastructure automation, reliability engineering | | qa-engineering | Quality assurance programs for confident, rapid software delivery | | security-expert | Application security engineering — threat modeling, secure code, OWASP prevention, supply chain security | | testing | Comprehensive testing practices (TDD, test design, CI/CD integration, performance testing) | | unity-dev-expert | Unity game development (C#, ECS/DOTS, physics, UI systems, multiplayer, performance) | | web-backend | Backend APIs and services (REST, GraphQL, microservices) | | web-frontend | Frontend web applications (SPAs, SSR, static sites, PWAs) |

Languages (10)

| Skill | Description | |-------|-------------| | cpp-expert | Principal-level C++ engineering (modern C++, RAII, concurrency, templates, performance) | | csharp-expert | Principal-level C# engineering (async, DI, EF Core, ASP.NET Core, testing) | | golang-expert | Principal-level Go engineering (concurrency, stdlib, production patterns, testing) | | java-expert | Principal-level Java engineering (JVM, Spring Boot, concurrency, JPA, testing) | | javascript-expert | Principal-level JavaScript & TypeScript engineering (Node.js, React, type system, testing) | | kotlin-expert | Principal-level Kotlin engineering (coroutines, multiplatform, Ktor, Spring Boot, testing) | | python-expert | Principal-level Python engineering (type system, async, testing, FastAPI, Django) | | ruby-expert | Principal-level Ruby engineering (idioms, concurrency, Rails, performance, testing) | | rust-expert | Principal-level Rust engineering (ownership, concurrency, unsafe, traits, async) | | swift-expert | Principal-level Swift engineering (concurrency, SwiftUI, protocols, testing, Apple platforms) |

Business (10)

| Skill | Description | |-------|-------------| | market-intelligence | Data source aggregation, sentiment analysis, trend detection, and risk signal monitoring | | marketing-expert | Brand positioning, campaign planning, market analysis, analytics, and growth frameworks | | predictive-maintenance | Industrial sensor monitoring, failure prediction, maintenance scheduling, and asset lifecycle | | product-manager | Customer-centric discovery, prioritization, and cross-functional execution | | project-manager | Planning, risk management, stakeholder alignment, and delivery tracking | | regulatory-sentinel | Compliance tracking, impact assessment, monitoring, and risk classification | | resource-allocator | Demand prediction, scheduling optimization, crisis management, and capacity modeling | | strategic-negotiator | Game theory, deal structuring, scenario modeling, and contract analysis | | supply-chain | Supply chain operations, procurement, logistics, and vendor management | | supply-chain-harmonizer | Disruption response, autonomous rerouting, inventory rebalancing, and scenario simulation |

Creative (4)

| Skill | Description | |-------|-------------| | brand-guardian | Brand voice enforcement, visual identity compliance, and content review workflows | | content-creation-expert | Content strategy, copywriting, SEO content, multimedia production, and editorial ops | | social-media-expert | Platform strategy, content planning, audience growth, community management, and analytics | | ux-designer | User research, interaction design, design systems, accessibility, and emotional design |

Professional (5)

| Skill | Description | |-------|-------------| | documentation | Technical documentation standards (READMEs, API docs, ADRs, code comments) | | executive-assistant | Scheduling, correspondence, meeting management, and executive workflow optimization | | grant-writer | Proposal strategy, narrative development, budget justification, and funder research | | knowledge-synthesis | Document ingestion, knowledge graphs, search/retrieval, summarization, and research workflows | | research-assistant | Literature review, source evaluation, citation management, and synthesis reporting |

Education (1)

| Skill | Description | |-------|-------------| | educator | Evidence-based teaching, learning retention, gamification, and assessment design |

Agents (1)

| Skill | Description | |-------|-------------| | utility-agent | AI agent utilities with context management and hallucination prevention |

What Gets Installed

IDE Mode (default)

Every skill installation includes foundational shared rules plus domain-specific rules:

Shared (always included):

| File | Description | |------|-------------| | core-principles.mdc | Honesty, simplicity, testing requirements | | code-quality.mdc | SOLID, DRY, clean code patterns | | security-fundamentals.mdc | Zero trust, input validation, secrets management | | git-workflow.mdc | Commits, branches, PRs, safety protocols | | communication.mdc | Direct, objective, professional communication |

Skill-specific rules — each skill adds domain-focused .mdc rule files. For example, web-frontend adds:

• accessibility.mdc — WCAG compliance, ARIA patterns
• component-patterns.mdc — React/Vue/Svelte best practices
• performance.mdc — Core Web Vitals, optimization
• state-management.mdc — State patterns, data flow
• styling.mdc — CSS architecture, design systems
• testing.mdc — Unit, integration, E2E testing

Rule file format (.mdc): Every file has YAML front matter with description and alwaysApply. Shared rules use alwaysApply: true; skill-specific rules use alwaysApply: false and load when relevant.

Adapter Mode

When using --adapter, no IDE files are installed. Instead, a single prompt file is generated in the format required by the target framework. Output varies by adapter:

| Adapter | Output | |---------|--------| | raw | <skill-name>.md — plain markdown prompt | | claude-code | Prompt formatted as a CLAUDE.md section | | gemini | Prompt formatted as a GEMINI.md section | | cursor | .cursor/rules/<skill-name>.mdc | | copilot | Prompt formatted for .github/copilot-instructions.md | | codex | AGENTS.md + .agents/skills/<name>/SKILL.md | | openai-agents | Python snippet: Agent(name=..., instructions=...) | | langchain | Python snippet: SystemMessagePromptTemplate.from_template(...) | | crewai | Python snippet: Agent(role=..., goal=..., backstory=...) |

File Structure

After IDE install (npx @djm204/agent-skills web-frontend)

your-project/
├── CLAUDE.md                              # Development guide (Claude Code, Cursor)
├── GEMINI.md                              # Development guide (Gemini CLI)
├── AGENTS.md                              # Development guide (OpenAI Codex)
├── .cursor/
│   └── rules/                             # Rule files (Cursor IDE)
│       ├── core-principles.mdc                 # Shared
│       ├── code-quality.mdc                    # Shared
│       ├── security-fundamentals.mdc           # Shared
│       ├── git-workflow.mdc                    # Shared
│       ├── communication.mdc                   # Shared
│       ├── web-frontend-overview.mdc           # Skill-specific
│       ├── web-frontend-accessibility.mdc      # Skill-specific
│       ├── web-frontend-component-patterns.mdc # Skill-specific
│       ├── web-frontend-performance.mdc        # Skill-specific
│       ├── web-frontend-state-management.mdc   # Skill-specific
│       ├── web-frontend-styling.mdc            # Skill-specific
│       └── web-frontend-testing.mdc            # Skill-specific
└── .github/
    └── copilot-instructions.md            # Instructions (GitHub Copilot)

After adapter install (npx @djm204/agent-skills golang-expert --adapter=langchain)

your-project/
└── golang-expert.py                       # LangChain SystemMessagePromptTemplate snippet

Programmatic API

Install the package and import from the /api subpath:

npm install @djm204/agent-skills

import { loadSkill, composeSkills, listSkills, runTestSuite } from '@djm204/agent-skills/api';

// Load a single skill at a specific tier
const skill = await loadSkill('golang-expert', { tier: 'standard' });
console.log(skill.prompt); // ready-to-use prompt string

// Compose multiple skills (deduplicates shared fragments)
const composed = await composeSkills(['fullstack', 'testing'], { tier: 'minimal' });

// List all available skills
const skills = await listSkills();

// Run behavioral test cases against an LLM response
const suite = await loadTestSuite('golang-expert');
const results = await runTestSuite(suite, myLlmFn);

TypeScript types are included — no @types/ package needed.

Examples

New React Project

mkdir my-react-app && cd my-react-app
npm create vite@latest . -- --template react-ts
npx @djm204/agent-skills web-frontend
# or use shorthand:
npx @djm204/agent-skills frontend

Full-Stack Next.js Project

npx create-next-app@latest my-app
cd my-app
npx @djm204/agent-skills fullstack

Microservices Backend

cd my-api-service
npx @djm204/agent-skills web-backend devops-sre
# or use shorthands:
npx @djm204/agent-skills backend devops

ML/AI Project

cd my-ml-project
npx @djm204/agent-skills ml-ai data-engineering
# or use shorthands:
npx @djm204/agent-skills ml data

Unity Game Project

cd my-unity-game
npx @djm204/agent-skills unity

Marketing Team Workspace

cd marketing-workspace
npx @djm204/agent-skills marketing social-media content-creation

Docs and Research

npx @djm204/agent-skills docs research

LangChain Agent Pipeline

# Standard tier for a Go expert agent
npx @djm204/agent-skills golang-expert --adapter=langchain --out=./agents

# Compose a fullstack + testing specialist (minimal tokens)
npx @djm204/agent-skills fullstack,testing --adapter=langchain --tier=minimal --out=./agents

OpenAI Codex Skill

# Install a skill as a Codex-compatible skill directory
npx @djm204/agent-skills security-expert --adapter=codex

# With minimal tier for smaller context
npx @djm204/agent-skills golang-expert --adapter=codex --tier=minimal

CrewAI Multi-Agent Team

npx @djm204/agent-skills product-manager --adapter=crewai --out=./crew
npx @djm204/agent-skills web-frontend --adapter=crewai --out=./crew
npx @djm204/agent-skills qa-engineering --adapter=crewai --out=./crew

Roadmap

| Phase | What | Status | |-------|------|--------| | Honest positioning | Clarify what skills are (prompts) vs. what they aren't (agents) | Done | | Remove off-brand skills | Cut lifestyle skills, focus on dev/business (48 → 44) | Done | | Runtime composition | Dynamic skill loading based on task detection (--auto) | Done | | JSON skill export | Export skills as JSON manifest (--export) | Done | | Usage analytics | Local usage tracking with --stats and privacy controls | Done | | MCP servers | Generic MCP server — serve any skill's tools via serve command | Done | | Effectiveness benchmarks | A/B test prompts vs. no-prompts, publish results | Planned | | Model-specific tuning | Test and document per-model tier recommendations | Planned | | Real framework integrations | LangChain Runnables, CrewAI Agent subclasses | Future |

Requirements

• Node.js: 18.0.0 or higher
• Supported IDEs/Tools (IDE mode):
  • Cursor IDE (any version with .cursor/rules/ support)
  • Claude Code (reads CLAUDE.md automatically)
  • GitHub Copilot (reads .github/copilot-instructions.md)
• Supported Frameworks (adapter mode):
  • OpenAI Agents SDK, LangChain, CrewAI, or any LLM via raw

Troubleshooting

"Unknown option" or Missing Features

If you're getting errors for options that should exist, you may have a cached old version:

# Force latest version (recommended)
npx @djm204/agent-skills@latest [command]

# Clear npx cache
npx clear-npx-cache

# Or manually clear npm cache
npm cache clean --force

Verify Your Version

npx @djm204/agent-skills --version

The CLI will notify you if a newer version is available.

Update Global Installation

npm update -g @djm204/agent-skills

How to Contribute

Adding a New Skill Pack

Skill packs live in skills/<skill-name>/ and follow this structure:

skills/your-skill/
├── skill.yaml                   # Metadata and manifest
├── prompts/
│   ├── minimal.md               # ~700 tokens: behavioral rules + anti-patterns
│   ├── standard.md              # ~2,800 tokens: principles + patterns
│   └── comprehensive.md         # ~7,500 tokens: full reference with examples
└── tests/
    └── test_cases.yaml          # Behavioral test cases

skill.yaml format:

name: your-skill
version: 1.0.0
category: engineering          # engineering | languages | business | creative | professional | education | agents
tags: [tag1, tag2]
description:
  short: "One-line description"
  long: "Detailed description of what this skill does."
context_budget:
  minimal: 700
  standard: 2800
  comprehensive: 7500
composable_with:
  recommended: [skill-a, skill-b]
  enhances: [skill-c]
conflicts_with: []
requires_tools: false
requires_memory: false

Prompt guidelines:

• Each tier must be standalone (does not depend on other tiers)
• Prompts are behavioral guidance for AI assistants, not human documentation
• minimal.md: numbered rules + anti-patterns list only
• standard.md: prose-based principles, patterns, decision frameworks (no large code blocks)
• comprehensive.md: full reference with code examples and reference tables

test_cases.yaml format:

name: your-skill-tests
skill: your-skill
version: 1.0.0
cases:
  - id: descriptive-id
    description: What behavior this tests
    prompt: "A realistic question a developer might ask"
    expected:
      contains_any:
        - keyword1
        - keyword2
      not_contains:
        - bad answer phrase
      min_length: 80
    tags: [core, category]

Run npx @djm204/agent-skills --test your-skill to preview test cases, and check docs/skill-authoring-guide.md for the complete authoring reference.

Adding a Legacy Template (IDE rule files)

1. Create the template in the appropriate category directory:

templates/<category>/your-template/
└── .cursor/
    └── rules/
        ├── overview.mdc          # Scope and core principles (required)
        ├── topic-one.mdc
        └── topic-two.mdc

2. Follow existing patterns — look at templates/engineering/web-frontend/ for reference.
3. Add a category field to the template entry in src/index.js.

Testing

npm test                         # Run all tests (490+)
npm run validate:rules           # Check template rule sizes (<100 lines)
node bin/cli.js --list           # List all skills/templates
node bin/cli.js golang-expert --adapter=raw   # Test adapter output
node bin/cli.js --test golang-expert          # Preview test cases

Shared Rules

The templates/_shared/ directory contains rules included with every IDE installation:

• core-principles.mdc — Universal development principles
• code-quality.mdc — Clean code patterns
• security-fundamentals.mdc — Security basics
• git-workflow.mdc — Git conventions
• communication.mdc — AI communication style

Changes to shared rules affect all templates — be thoughtful with modifications.

Submitting a PR

1. Fork the repository
2. Create a branch: feat/your-skill-name
3. Add skill pack files and tests
4. Run npm test and ensure all tests pass
5. Submit a PR with a clear description of the skill's domain and behavioral focus

License

MIT © David Mendez