From df1b5272e486a35b9ff96be711d6e2a0c661f20f Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Sat, 11 Jul 2026 17:55:09 -0400 Subject: [PATCH] docs: prepare repository for GitHub contributors Signed-off-by: Magnus Hedemark --- .github/ISSUE_TEMPLATE/bug_report.md | 32 +++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 +++ .github/ISSUE_TEMPLATE/feature_request.md | 24 ++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 22 +++++++++++ .github/workflows/validate.yml | 22 +++++++++++ CODE_OF_CONDUCT.md | 23 +++++++++++ CONTRIBUTING.md | 48 +++++++++++++++++++++++ SECURITY.md | 20 ++++++++++ agent-council/SKILL.md | 2 +- flaresolverr-cli/SKILL.md | 7 ++-- 10 files changed, 201 insertions(+), 4 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/validate.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..2fdc29d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,32 @@ +--- +name: Bug report +about: Report a reproducible problem in a skill or its supporting files +title: "bug: " +labels: [bug] +assignees: [] +--- + +## Skill and version + +- Skill: +- Commit or release: +- Operating system: +- Agent framework or harness: + +## Problem + + + +## Steps to reproduce + +1. +2. +3. + +## Expected behavior + +## Actual behavior + +## Additional context + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..93ebc49 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Ask a question or discuss an idea + url: https://github.com/magnus919/agent-skills/discussions + about: Use Discussions for questions, exploration, and proposals that are not yet ready for an issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..1d9f5ba --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,24 @@ +--- +name: Feature request +about: Propose an improvement that fits the mission of agent-skills +title: "feat: " +labels: [enhancement] +assignees: [] +--- + +## Problem or use case + + + +## Proposed change + + + +## Alternatives considered + +## Scope + +- [ ] I checked the existing skills for overlap. +- [ ] This proposal can be implemented without private or deployment-specific assumptions. + +## Additional context diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..e3dda8d --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ +## Summary + + + +## Validation + +- [ ] `ruby scripts/validate-skills.rb` +- [ ] Skill-specific checks, if applicable: + +## Documentation + +- [ ] I updated the relevant `SKILL.md`, `README.md`, or reference files. +- [ ] Links are relative and resolve from a fresh clone. + +## Community and security + +- [ ] This pull request contains no credentials, private infrastructure details, or deployment-specific paths. +- [ ] I have disclosed meaningful AI assistance in the description or commit message. + +## Review notes + + diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..f1acb8c --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,22 @@ +name: Validate skills + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.3' + - name: Validate skill format and links + run: ruby scripts/validate-skills.rb diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..679bd12 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,23 @@ +# Code of Conduct + +## Our pledge + +We are committed to making participation in agent-skills a welcoming, respectful, and harassment-free experience for everyone, regardless of background, identity, experience, or technology choices. + +## Expected behavior + +- Be respectful and constructive. +- Assume good intent while addressing impact directly. +- Welcome questions and beginner contributions. +- Focus criticism on ideas, code, and documentation rather than people. +- Respect the project's privacy and security boundaries. + +## Unacceptable behavior + +Harassment, discrimination, personal attacks, doxxing, sexualized behavior, threats, and publishing private information are not acceptable. Deliberate attempts to compromise users, contributors, or their systems are also prohibited. + +## Enforcement + +Report problems privately to the repository owner through the contact method listed in the repository's security policy. Reports will be reviewed and handled as confidentially as practical. Maintainers may remove comments, close discussions, or restrict participation when necessary to protect the community. + +This code of conduct is adapted from the Contributor Covenant, version 2.1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e72c98a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing to agent-skills + +Thanks for helping improve agent-skills. Contributions should make a skill more useful, more portable, or easier for humans and agents to discover. + +## Before you start + +- Read `AGENTS.md` for repository-wide conventions. +- Read the target skill's `SKILL.md` and `README.md` before changing it. +- For a new skill or a substantial change, open an issue first so the scope can be discussed. +- Do not include credentials, private infrastructure details, or deployment-specific paths. + +## Skill requirements + +Each skill must: + +- Live in its own directory with a matching lowercase, hyphenated name. +- Include `SKILL.md` with valid YAML frontmatter. +- Include a human-facing `README.md` with the required sections described in `AGENTS.md`. +- Keep core instructions concise and put deeper material in `references/`, `templates/`, or `scripts/`. +- Use relative links that work from a fresh clone. +- Describe when the skill should be loaded, and identify the nearest alternative when overlap matters. + +## Development + +Clone the repository and run the validator from its root: + +```sh +git clone https://github.com/magnus919/agent-skills.git +cd agent-skills +ruby scripts/validate-skills.rb +``` + +The same validation runs in GitHub Actions for pushes and pull requests. If a skill includes executable scripts or a package, run its documented checks as well and include the commands and results in your pull request. + +## Pull requests + +- Create a branch from `main`: `feat/short-description`, `fix/short-description`, or `docs/short-description`. +- Keep each pull request focused on one logical change. +- Use a clear Conventional Commit subject, such as `feat(skill): add ...` or `fix(skill): ...`. +- Add or update documentation with the behavior it describes. +- Do not force-push after review unless a maintainer asks you to. +- Complete the pull request checklist and disclose meaningful AI assistance. + +A maintainer may ask for an issue before reviewing a large design change. Small documentation fixes and clear bug fixes can go directly to a pull request. + +## License + +By contributing, you agree that your contribution is released under the MIT License in this repository. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..61aea98 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,20 @@ +# Security policy + +## Reporting a vulnerability + +Please do not open a public issue for a security vulnerability. Use GitHub's private vulnerability reporting for this repository if it is enabled. If it is unavailable, contact the repository owner through the public contact method on the GitHub profile and include `agent-skills security` in the subject. + +Include: + +- The affected skill, file, or release +- A clear description of the impact +- Reproduction steps or a minimal proof of concept +- Any suggested mitigation + +Do not include credentials, private URLs, or personal data in the report unless they are necessary to reproduce the issue. + +## Response + +You should receive an acknowledgement within seven days. We will investigate, keep the reporter informed when practical, and coordinate disclosure after a fix or mitigation is available. + +Supported versions are the latest commit on `main` and the most recent tagged release. Older releases may receive security fixes when the impact warrants it. diff --git a/agent-council/SKILL.md b/agent-council/SKILL.md index 691be18..bf7a7ca 100644 --- a/agent-council/SKILL.md +++ b/agent-council/SKILL.md @@ -9,7 +9,7 @@ description: >- license: MIT compatibility: Requires Python 3.10+ and pydantic-ai. CLI tool installs via pip. metadata: - source: https://git.brandyapple.com/magnus/agent-skills/agent-council + source: https://github.com/magnus919/agent-skills/tree/main/agent-council spec-version: "1.1" --- diff --git a/flaresolverr-cli/SKILL.md b/flaresolverr-cli/SKILL.md index a595931..334d325 100644 --- a/flaresolverr-cli/SKILL.md +++ b/flaresolverr-cli/SKILL.md @@ -6,12 +6,13 @@ description: 'Interact with a FlareSolverr proxy server from the terminal: healt FlareSolverr, Cloudflare bypass, anti-bot proxy, headless browser proxy, or needs to fetch a page behind Cloudflare protection.' license: MIT -compatibility: Python 3.8+ (stdlib only, no pip deps). Requires a running FlareSolverr +compatibility: >- + Python 3.8+ (stdlib only, no pip deps). Requires a running FlareSolverr instance (Docker: ghcr.io/flaresolverr/flaresolverr) and the FLARESOLVERR_URL env var set to the server address (defaults to http://localhost:8191). metadata: tags: flaresolverr, cloudflare, proxy, anti-bot, headless-browser, selenium, web-scraping - sources: https://github.com/FlareSolverr/FlareSolverr, https://hub.docker.com/r/flaresolverr/flaresolverr + sources: "https://github.com/FlareSolverr/FlareSolverr, https://hub.docker.com/r/flaresolverr/flaresolverr" --- # flaresolverr-cli — Cloudflare Bypass Proxy from the Terminal @@ -143,6 +144,6 @@ flaresolverr-cli --timeout 30 request get --url https://example.com ## References -- [scripts/flaresolverr-cli](scripts/flaresolverr-cli) — The CLI binary. Stdlib-only Python 3.8+; no pip dependencies. Built following cli-builder patterns: `--json`, `--dry-run`, `--quiet`, bounded `--timeout`, dual-output via `emit()`. +- [Related FlareSolverr CLI](../flaresolverr/scripts/flaresolverr) — Stdlib-only reference implementation for the same API. - [FlareSolverr GitHub](https://github.com/FlareSolverr/FlareSolverr) — Source, API docs, Docker Compose examples. - [FlareSolverr Docker Hub](https://hub.docker.com/r/flaresolverr/flaresolverr) — Prebuilt images.