---
slug: "auto-skill-matrixy"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/matrixy/auto-skill@main/README.md"
repo: "https://github.com/matrixy/auto-skill"
source_file: "README.md"
branch: "main"
---
<p align="center">
  <img src="https://raw.githubusercontent.com/MaTriXy/auto-skill/main/website/static/img/logo.png" alt="Auto-Skill Logo" width="120" />
</p>

# Auto-Skill

**Automatically learn from your workflows and turn them into intelligent, context-aware skills.**

Auto-Skill v5.0 introduces **Proactive Skill Discovery** - a closed-loop learning system that observes your coding sessions, detects repeated patterns, and **proactively suggests relevant community skills** from 27,000+ external sources before you even ask. It combines local pattern detection with external skill discovery, cross-agent sharing, and anonymous telemetry.

[![npm](https://img.shields.io/npm/v/@matrixy/auto-skill)](https://www.npmjs.com/package/@matrixy/auto-skill)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-Docusaurus-blue.svg)](https://MaTriXy.github.io/auto-skill)


https://github.com/user-attachments/assets/7f0bf716-9c7a-47bd-86f4-92fe62be128b

## Quick Start

```bash
npx skills add MaTriXy/auto-skill
```

### Install CLI

```bash
npm install -g @matrixy/auto-skill
```

Once installed, the plugin automatically:
1. Records your tool usage patterns
2. Detects repeated workflows (3+ occurrences)
3. Offers to create skills from high-confidence patterns

## CLI

```bash
auto-skill init                # Initialize config and directories
auto-skill discover            # Discover patterns for current project
auto-skill stats               # Show adoption statistics
auto-skill graduate            # Manage skill graduation
auto-skill agents list         # List known coding agents
auto-skill agents detect       # Detect installed agents
auto-skill lock status         # Show lock file status
auto-skill lock verify         # Verify skill integrity (SHA-256)
auto-skill lock list           # List locked skills
auto-skill telemetry report    # Show effectiveness report
auto-skill telemetry events    # Show raw events
auto-skill version             # Show version
```

All commands support `--json` output.

**For skill search and installation**, use [Skills CLI](https://skills.sh/docs/cli):
```bash
npx skills find [query]        # Interactive skill search
npx skills add owner/repo      # Install skills from GitHub
npx skills list                # List installed skills
```

## Key Features

### 🚀 **NEW in v5.0: Proactive Skill Discovery**
- **Context-Aware Recommendations** — Automatically suggests community skills based on detected frameworks, languages, and intent
- **27,000+ External Skills** — Search and load from [Skills.sh](https://skills.sh) in real-time
- **Hybrid Learning** — Combines local pattern detection with external skill discovery
- **Smart Graduation** — Suggests upgrading local patterns to battle-tested community skills
- **Zero-Config Search** — Works out of the box, GitHub token optional for higher rate limits

### 🎯 Core Features
- **Pattern Detection** — Automatically detects repeated tool sequences across sessions
- **Session Analysis** — Identifies intent (debug, implement, refactor) and workflow types (TDD, etc.)
- **18 Design Patterns** — Architectural, coding, and workflow pattern recognition
- **Mental Model Integration** — Semantic codebase understanding via [@mentalmodel/cli](https://github.com/Michaelliv/mental)
- **Multi-Agent Support** — Cross-agent skill sharing (Claude Code, Codex, Cursor, Aider, etc.) via symlinks
- **Provider System** — Pluggable skill discovery (local, Skills.sh, RFC 8615 well-known endpoints)
- **Lock File** — SHA-256 integrity verification with atomic writes
- **Spec Compliance** — Generated skills validated against [agentskills.io](https://agentskills.io) spec
- **Path Security** — Traversal prevention, null byte blocking, unicode normalization
- **Confidence Evolution** — Skills improve from 50% (external) → 75% (proven) → 85% (graduated)
- **Anonymous Telemetry** — Privacy-first usage tracking ([details below](#telemetry))

## Proactive Discovery Example

```typescript
import {
  createExternalSkillLoader,
  createProactiveDiscovery,
  createSkillRecommendationEngine,
} from '@matrixy/auto-skill';

const loader = createExternalSkillLoader({
  githubToken: process.env.GITHUB_TOKEN, // Optional
});

const discovery = createProactiveDiscovery(loader);
const engine = createSkillRecommendationEngine(loader, discovery);

await loader.start();

// Search community skills
const response = await loader.search('react testing', { limit: 5 });
console.log(response.skills);

// Get context-aware recommendations
const recommendations = await engine.recommendForPattern(detectedPattern);
console.log(recommendations);
// [
//   {
//     type: 'hybrid',
//     externalSkill: { title: 'React Test Patterns', ... },
//     localPattern: { ... },
//     reason: 'Your workflow matches "React Test Patterns". Use it instead?',
//     confidence: 0.9,
//     action: 'graduate'
//   }
// ]

await loader.stop();
```

**See [`examples/proactive-discovery.ts`](https://github.com/matrixy/auto-skill/blob/HEAD/examples/proactive-discovery.ts) for complete examples.**

## Documentation

**Full documentation: [https://MaTriXy.github.io/auto-skill](https://MaTriXy.github.io/auto-skill)**

### New in v5.0
- 🎉 [Release Announcement](https://MaTriXy.github.io/auto-skill) — What's new in v5.0
- 📚 [Proactive Discovery Guide](https://MaTriXy.github.io/auto-skill/docs/features/proactive-discovery) — Complete usage guide
- 🎯 [Example Code](https://github.com/matrixy/auto-skill/blob/HEAD/examples/proactive-discovery.ts) — 5 runnable examples

## Development

```bash
git clone https://github.com/MaTriXy/auto-skill.git
cd auto-skill
npm install
npm test
```

## Telemetry

This tool collects **anonymous, aggregate metrics** (event types, counts, timing, OS) to improve the experience. No PII, search queries, file paths, or session data is collected.

**Disable:**
```bash
export AUTO_SKILL_NO_TELEMETRY=1  # or DO_NOT_TRACK=1
```

Automatically disabled in CI. Source: [`src/core/telemetry.ts`](https://github.com/matrixy/auto-skill/blob/HEAD/src/core/telemetry.ts)

## License

MIT License - see [LICENSE](https://github.com/matrixy/auto-skill/tree/HEAD/LICENSE)

---

**Version 5.0.0** | [Repository](https://github.com/MaTriXy/auto-skill) | [Issues](https://github.com/MaTriXy/auto-skill/issues) | [Changelog](https://github.com/matrixy/auto-skill/blob/HEAD/CHANGELOG.md)