A curated collection of reusable AI agent skills/prompts plus skillsctl — a production-quality, safe-by-default CLI for scanning, auditing, planning, fixing, and migrating skill files across multiple repositories.

1. What are Skills?
2. Repository Layout
3. Skill Schema
4. How to Add a Skill
5. skillsctl – CLI Reference
6. Embeddings & Semantic Search
7. Scanning Repos and Creating PRs – Workflow
8. Configuration
9. Development

A skill is a reusable, versioned prompt or instruction set for an AI agent. Skills are stored as Markdown files with YAML frontmatter so they are both human-readable and machine-parseable.

Skills encapsulate:

• What the agent should do (body / prompt text)
• Metadata for routing, discovery, and tooling constraints (frontmatter)
• Verification guidance to confirm the skill works correctly

agent-skills/
├── skills/                     # Managed skill files
│   └── <domain>/
│       └── <skill-id>.md
├── skillsctl/                  # The CLI tool (Python package)
│   ├── cli.py                  # Click entrypoint
│   ├── scan.py                 # Repo scanning
│   ├── audit.py                # Rule-based audit
│   ├── plan.py                 # Improvement planning
│   ├── fix.py                  # Auto-fix engine
│   ├── migrate.py              # Cross-repo migration
│   ├── rules.py                # Rule fetching & management
│   ├── schema.py               # JSON Schema + validation helpers
│   └── embed.py                # Embeddings / BM25 search (optional)
├── tests/                      # Unit tests + fixtures
├── pyproject.toml
└── README.md                   # This file

Every skill file must have a YAML frontmatter block between --- delimiters. The following fields are required:

Optional fields:

The full JSON Schema is defined in skillsctl/schema.py.

1. Choose a domain (e.g., code-review, testing, documentation).
2. Create skills/<domain>/<your-skill-id>.md.
3. Add the required frontmatter (see Skill Schema above).
4. Write the skill body — include a heading, instructions, and at least one usage example.
5. Validate locally:

   skillsctl audit --file skills/<domain>/<your-skill-id>.md

6. Open a pull request.

# From the repo root
pip install -e .

# With embeddings support
pip install -e ".[embeddings]"

# Development (includes ruff, pytest, etc.)
pip install -e ".[dev]"

All commands default to dry-run / read-only mode.

• Pass --apply to write changes to disk.
• Pass --apply --allow-delete to enable deletion of source files.
• --dry-run is the default; pass --no-dry-run together with --apply to mutate files.

Clone/fetch repos and detect candidate skill/prompt files by heuristics.

skillsctl scan --repo droxey/dotfiles --repo droxey/clincher
skillsctl scan --local ./my-repo
skillsctl scan --repo droxey/ai --output my-manifest.json

Outputs a scan manifest (JSON) listing every candidate file with its content hash and parsed frontmatter.

Audit candidate files against a ruleset derived from mgechev/skills-best-practices.

skillsctl audit --manifest scan-manifest.json
skillsctl audit --file skills/general/hello-world.md
skillsctl audit --offline   # use built-in baseline rules only

Outputs audit-report.json and audit-report.md.

The rule source metadata (URL + commit SHA + timestamp) is recorded in every report for reproducibility.

Built-in rules:

Produce a prioritised improvement plan from audit findings.

skillsctl plan --audit-report audit-report.json

Outputs improvement-plan.json and improvement-plan.md, ranked by severity -> effort -> fixability.

Apply safe, deterministic fixes in-place (requires --apply).

# Dry-run (default)
skillsctl fix --plan-file improvement-plan.json

# Apply fixes
skillsctl fix --plan-file improvement-plan.json --apply --no-dry-run

Auto-fixable rules: FM001, FM004, FM005, ST001. After fixing, a re-audit runs automatically to show improvements.

Move skill files from source repos into this repo under skills/<domain>/.

# Dry-run
skillsctl migrate --manifest scan-manifest.json

# Apply (writes migrated files, leaves pointer in source)
skillsctl migrate --manifest scan-manifest.json --apply --no-dry-run

# Apply + delete source files
skillsctl migrate --manifest scan-manifest.json --apply --no-dry-run --allow-delete

skillsctl includes an optional embeddings module (skillsctl/embed.py).

Embeddings are cached at ~/.cache/skillsctl/embeddings.json (keyed by content SHA-256). Override with SKILLSCTL_CACHE_DIR.

Embeddings are never required to run the CLI or tests.

# 1. Scan source repos
skillsctl scan \
  --repo droxey/dotfiles \
  --repo droxey/clincher \
  --repo droxey/ai \
  --output scan-manifest.json

# 2. Audit the candidates
skillsctl audit --manifest scan-manifest.json

# 3. Plan improvements
skillsctl plan --audit-report audit-report.json

# 4. Apply safe fixes (optional)
skillsctl fix --plan-file improvement-plan.json --apply --no-dry-run

# 5. Migrate skills into this repo
skillsctl migrate --manifest scan-manifest.json --apply --no-dry-run

Policy: one PR per source repository is created when migration is applied, containing pointer stubs for each migrated skill.

pip install -e ".[dev]"

# Lint
ruff check skillsctl/ tests/
ruff format --check skillsctl/ tests/

# Test
pytest tests/ -v
pytest tests/ --cov=skillsctl --cov-report=term-missing

CI runs on every push/PR via .github/workflows/ci.yml.