{"id":47689032,"url":"https://github.com/droxey/agent-skills","last_synced_at":"2026-04-02T15:14:57.927Z","repository":{"id":343146742,"uuid":"1176469548","full_name":"droxey/agent-skills","owner":"droxey","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-09T04:13:45.000Z","size":120,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-09T09:29:02.332Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/droxey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-09T03:46:12.000Z","updated_at":"2026-03-09T04:13:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/droxey/agent-skills","commit_stats":null,"previous_names":["droxey/agent-skills"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/droxey/agent-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/droxey%2Fagent-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/droxey%2Fagent-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/droxey%2Fagent-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/droxey%2Fagent-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/droxey","download_url":"https://codeload.github.com/droxey/agent-skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/droxey%2Fagent-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31308768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T15:14:56.900Z","updated_at":"2026-04-02T15:14:57.918Z","avatar_url":"https://github.com/droxey.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-skills\n\nA curated collection of reusable AI agent skills/prompts plus **`skillsctl`** — a\nproduction-quality, safe-by-default CLI for scanning, auditing, planning, fixing,\nand migrating skill files across multiple repositories.\n\n---\n\n## Table of Contents\n\n1. [What are Skills?](#what-are-skills)\n2. [Repository Layout](#repository-layout)\n3. [Skill Schema](#skill-schema)\n4. [How to Add a Skill](#how-to-add-a-skill)\n5. [skillsctl – CLI Reference](#skillsctl--cli-reference)\n6. [Embeddings \u0026 Semantic Search](#embeddings--semantic-search)\n7. [Scanning Repos and Creating PRs – Workflow](#scanning-repos-and-creating-prs--workflow)\n8. [Configuration](#configuration)\n9. [Development](#development)\n\n---\n\n## What are Skills?\n\nA **skill** is a reusable, versioned prompt or instruction set for an AI agent.\nSkills are stored as Markdown files with YAML frontmatter so they are both\nhuman-readable and machine-parseable.\n\nSkills encapsulate:\n- **What** the agent should do (body / prompt text)\n- **Metadata** for routing, discovery, and tooling constraints (frontmatter)\n- **Verification** guidance to confirm the skill works correctly\n\n---\n\n## Repository Layout\n\n```\nagent-skills/\n├── skills/                     # Managed skill files\n│   └── \u003cdomain\u003e/\n│       └── \u003cskill-id\u003e.md\n├── skillsctl/                  # The CLI tool (Python package)\n│   ├── cli.py                  # Click entrypoint\n│   ├── scan.py                 # Repo scanning\n│   ├── audit.py                # Rule-based audit\n│   ├── plan.py                 # Improvement planning\n│   ├── fix.py                  # Auto-fix engine\n│   ├── migrate.py              # Cross-repo migration\n│   ├── rules.py                # Rule fetching \u0026 management\n│   ├── schema.py               # JSON Schema + validation helpers\n│   └── embed.py                # Embeddings / BM25 search (optional)\n├── tests/                      # Unit tests + fixtures\n├── pyproject.toml\n└── README.md                   # This file\n```\n\n---\n\n## Skill Schema\n\nEvery skill file must have a YAML frontmatter block between `---` delimiters.\nThe following fields are **required**:\n\n| Field         | Type                 | Description                         |\n|---------------|----------------------|-------------------------------------|\n| `id`          | `string`             | Stable kebab-case identifier        |\n| `name`        | `string`             | Human-readable display name         |\n| `description` | `string` (\u003e=10 chars)| One-sentence description            |\n| `version`     | `string`             | Semantic version (MAJOR.MINOR.PATCH)|\n| `tags`        | `string[]` (\u003e=1)     | Taxonomy tags for discovery/routing |\n\nOptional fields:\n\n| Field          | Type       | Description                                       |\n|----------------|------------|---------------------------------------------------|\n| `inputs`       | `object[]` | Declared input variables                          |\n| `outputs`      | `object[]` | Declared output variables                         |\n| `tooling`      | `object`   | Model/tool constraints                            |\n| `verification` | `string`   | How to verify the skill produces correct output   |\n| `source`       | `string`   | Original repo URL (populated by `migrate`)        |\n| `migrated_at`  | `string`   | ISO-8601 migration timestamp                      |\n\nThe full JSON Schema is defined in `skillsctl/schema.py`.\n\n---\n\n## How to Add a Skill\n\n1. Choose a domain (e.g., `code-review`, `testing`, `documentation`).\n2. Create `skills/\u003cdomain\u003e/\u003cyour-skill-id\u003e.md`.\n3. Add the required frontmatter (see Skill Schema above).\n4. Write the skill body — include a heading, instructions, and at least one usage example.\n5. Validate locally:\n   ```bash\n   skillsctl audit --file skills/\u003cdomain\u003e/\u003cyour-skill-id\u003e.md\n   ```\n6. Open a pull request.\n\n---\n\n## skillsctl – CLI Reference\n\n### Installation\n\n```bash\n# From the repo root\npip install -e .\n\n# With embeddings support\npip install -e \".[embeddings]\"\n\n# Development (includes ruff, pytest, etc.)\npip install -e \".[dev]\"\n```\n\n### Safety Rails\n\nAll commands default to dry-run / read-only mode.\n\n- Pass `--apply` to write changes to disk.\n- Pass `--apply --allow-delete` to enable deletion of source files.\n- `--dry-run` is the default; pass `--no-dry-run` together with `--apply` to mutate files.\n\n### `scan`\n\nClone/fetch repos and detect candidate skill/prompt files by heuristics.\n\n```bash\nskillsctl scan --repo droxey/dotfiles --repo droxey/clincher\nskillsctl scan --local ./my-repo\nskillsctl scan --repo droxey/ai --output my-manifest.json\n```\n\nOutputs a **scan manifest** (JSON) listing every candidate file with its content hash and parsed frontmatter.\n\n### `audit`\n\nAudit candidate files against a ruleset derived from `mgechev/skills-best-practices`.\n\n```bash\nskillsctl audit --manifest scan-manifest.json\nskillsctl audit --file skills/general/hello-world.md\nskillsctl audit --offline   # use built-in baseline rules only\n```\n\nOutputs `audit-report.json` and `audit-report.md`.\n\nThe rule source metadata (URL + commit SHA + timestamp) is recorded in every report for reproducibility.\n\n**Built-in rules:**\n\n| ID    | Severity | Description                   |\n|-------|----------|-------------------------------|\n| FM001 | error    | Missing frontmatter           |\n| FM002 | error    | Invalid frontmatter schema    |\n| FM003 | error    | Missing required field        |\n| FM004 | warning  | Non-kebab-case `id`           |\n| FM005 | warning  | Invalid semver `version`      |\n| CT001 | warning  | No descriptive body text      |\n| CT002 | info     | No usage example              |\n| CT003 | info     | Missing `verification` field  |\n| CT004 | warning  | No taxonomy tags              |\n| ST001 | info     | No Markdown heading           |\n\n### `plan`\n\nProduce a prioritised improvement plan from audit findings.\n\n```bash\nskillsctl plan --audit-report audit-report.json\n```\n\nOutputs `improvement-plan.json` and `improvement-plan.md`, ranked by severity -\u003e effort -\u003e fixability.\n\n### `fix`\n\nApply safe, deterministic fixes in-place (requires `--apply`).\n\n```bash\n# Dry-run (default)\nskillsctl fix --plan-file improvement-plan.json\n\n# Apply fixes\nskillsctl fix --plan-file improvement-plan.json --apply --no-dry-run\n```\n\nAuto-fixable rules: FM001, FM004, FM005, ST001.\nAfter fixing, a re-audit runs automatically to show improvements.\n\n### `migrate`\n\nMove skill files from source repos into this repo under `skills/\u003cdomain\u003e/`.\n\n```bash\n# Dry-run\nskillsctl migrate --manifest scan-manifest.json\n\n# Apply (writes migrated files, leaves pointer in source)\nskillsctl migrate --manifest scan-manifest.json --apply --no-dry-run\n\n# Apply + delete source files\nskillsctl migrate --manifest scan-manifest.json --apply --no-dry-run --allow-delete\n```\n\n---\n\n## Embeddings \u0026 Semantic Search\n\n`skillsctl` includes an optional embeddings module (`skillsctl/embed.py`).\n\n| Condition                                        | Behaviour                              |\n|--------------------------------------------------|----------------------------------------|\n| `OPENAI_API_KEY` set + `openai` package installed| Dense embeddings (text-embedding-3-small) |\n| API key missing or package absent                | Automatic BM25 lexical search fallback |\n\nEmbeddings are cached at `~/.cache/skillsctl/embeddings.json` (keyed by content SHA-256).\nOverride with `SKILLSCTL_CACHE_DIR`.\n\nEmbeddings are never required to run the CLI or tests.\n\n---\n\n## Scanning Repos and Creating PRs – Workflow\n\n```bash\n# 1. Scan source repos\nskillsctl scan \\\n  --repo droxey/dotfiles \\\n  --repo droxey/clincher \\\n  --repo droxey/ai \\\n  --output scan-manifest.json\n\n# 2. Audit the candidates\nskillsctl audit --manifest scan-manifest.json\n\n# 3. Plan improvements\nskillsctl plan --audit-report audit-report.json\n\n# 4. Apply safe fixes (optional)\nskillsctl fix --plan-file improvement-plan.json --apply --no-dry-run\n\n# 5. Migrate skills into this repo\nskillsctl migrate --manifest scan-manifest.json --apply --no-dry-run\n```\n\nPolicy: one PR per source repository is created when migration is applied,\ncontaining pointer stubs for each migrated skill.\n\n---\n\n## Configuration\n\n| Environment Variable  | Default              | Description                            |\n|-----------------------|----------------------|----------------------------------------|\n| `OPENAI_API_KEY`      | –                    | Enables dense-vector embeddings        |\n| `EMBEDDINGS_API_KEY`  | –                    | Alternative key (any OpenAI-compat API)|\n| `EMBEDDINGS_API_BASE` | –                    | Custom base URL for embeddings API     |\n| `SKILLSCTL_CACHE_DIR` | `~/.cache/skillsctl` | Embeddings cache directory             |\n\n---\n\n## Development\n\n```bash\npip install -e \".[dev]\"\n\n# Lint\nruff check skillsctl/ tests/\nruff format --check skillsctl/ tests/\n\n# Test\npytest tests/ -v\npytest tests/ --cov=skillsctl --cov-report=term-missing\n```\n\nCI runs on every push/PR via `.github/workflows/ci.yml`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdroxey%2Fagent-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdroxey%2Fagent-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdroxey%2Fagent-skills/lists"}