diff --git a/.github/MAINTENANCE.md b/.github/MAINTENANCE.md index 8dd759d..16fc4c7 100644 --- a/.github/MAINTENANCE.md +++ b/.github/MAINTENANCE.md @@ -1,77 +1,60 @@ -# Repository Maintenance Protocol +# Repository Maintenance Protocol & Governance > [!URGENT] > **READ THIS FIRST**: The single most critical rule of this repository is: **IF YOU DO NOT PUSH YOUR CHANGES, THEY DO NOT EXIST.** > > **ALWAYS** run `git push` immediately after committing. No exceptions. -To ensure consistency and quality, the following steps MUST be performed for **every single request** involving skills or documentation. +## 1. Governance & Roles -## 1. Analysis & Pre-Flight (Planner Role) +### Maintainers -Before writing any code: +- **Core Team**: Responsible for "Official" skills and merging PRs. +- **Review Policy**: All PRs must pass the [Quality Bar](../docs/QUALITY_BAR.md) checks. -- [ ] **Analyze Request**: Understand if it's a new skill, a fix, or a tool link. -- [ ] **Check Duplicates**: Run `grep -r "search_term" skills_index.json` to ensure the skill doesn't already exist. -- [ ] **Plan Integration**: Decide on the folder name and category. +### Code of Conduct -## 2. Implementation & Standardization (Executor Role) +All contributors must adhere to the [Code of Conduct](../CODE_OF_CONDUCT.md). -- [ ] **Folder Structure**: Create `skills//`. -- [ ] **SKILL.md**: Create the file with valid frontmatter. **strict format**: +## 2. Analysis & Planning (Planner Role) - ```markdown - --- - name: Skill Name - description: Brief description (max 100 chars). - --- - ``` +1. **Check Duplicates**: `grep -r "search_term" skills_index.json` +2. **Consult Quality Bar**: Review `docs/QUALITY_BAR.md` to ensure the plan meets the "Validated" criteria. +3. **Risk Assessment**: Determine if the skill is `safe`, `critical`, or `offensive`. (See [Security Guardrails](../docs/SECURITY_GUARDRAILS.md)) -- [ ] **Content**: Ensure the skill instructions are clear and the `code` is functional. +## 3. Implementation Workflow (Executor Role) -## 3. Validation Chain (MANDATORY & BLOCKING) +1. **Create Skill**: Follow the standard folder structure `skills//`. +2. **SKILL.md**: MUST header to the Quality Bar standard. -You **MUST** run these scripts in order. If _any_ script fails, **STOP** and fix it. - -1. **Validate Structure**: - - ```bash - python3 scripts/validate_skills.py + ```yaml + --- + name: my-skill + description: clear description + risk: safe + source: self + --- ``` -2. **Update Index**: +3. **Security Check**: If `risk: offensive`, add the "Authorized Use Only" disclaimer. - ```bash - python3 scripts/generate_index.py - ``` +## 4. Validation Chain (MANDATORY) -3. **Sync Documentation**: +Run strict validation before committing: - ```bash - python3 scripts/update_readme.py - ``` +```bash +python3 scripts/validate_skills.py --strict +python3 scripts/generate_index.py +python3 scripts/update_readme.py +``` -## 4. Documentation & Credits (CRITICAL) +## 5. Documentation & Credits -- [ ] **Update README Credits**: Manually add the source link in the `## Credits & Sources` section of `README.md`. - - Format: `- **[Repo Name](Url)**: Description of usage.` +- [ ] **SOURCE.md**: Update the master source list if importing external skills. +- [ ] **README.md**: Ensure credits are added in the `Credits` section. -## 5. Finalization (The "Antigravity" Standard) +## 6. Finalization (The "Antigravity" Standard) -- [ ] **Git Status**: Check what you are about to commit. - [ ] **Git Add**: `git add .` -- [ ] **Commit**: `git commit -m "feat: add [skill-name] skill"`. -- [ ] **PUSH**: - - > [!CRITICAL] - > **EXECUTE THIS IMMEDIATELY**: `git push` - > - > Do not wait. Do not "batch" later. Push NOW. - -## 6. Release (If Applicable) - -If this is a consolidated release: - -- [ ] `git tag -a vX.Y.Z -m "Release X.Y.Z"` -- [ ] `git push origin vX.Y.Z` -- [ ] `gh release create vX.Y.Z --generate-notes` +- [ ] **Commit**: `git commit -m "feat: add [skill-name] skill"` +- [ ] **PUSH NOW**: `git push` (Do not wait). diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f7d890f..6865c20 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,17 +1,22 @@ -## Description +# Pull Request Description -Please describe your changes. What skill are you adding or modifying? +Please include a summary of the change and which skill is added or fixed. -## Checklist +## Quality Bar Checklist ✅ -- [ ] My skill follows the [creation guidelines](https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/skill-creator) -- [ ] I have run `validate_skills.py` -- [ ] I have added my name to the credits (if applicable) +**All items must be checked before merging.** + +- [ ] **Standards**: I have read `docs/QUALITY_BAR.md` and `docs/SECURITY_GUARDRAILS.md`. +- [ ] **Metadata**: The `SKILL.md` frontmatter is valid (checked with `scripts/validate_skills.py`). +- [ ] **Risk Label**: I have assigned the correct `risk:` tag (`none`, `safe`, `critical`, `offensive`). +- [ ] **Triggers**: The "When to use" section is clear and specific. +- [ ] **Security**: If this is an _offensive_ skill, I included the "Authorized Use Only" disclaimer. +- [ ] **Local Test**: I have verified the skill works locally. +- [ ] **Credits**: I have added the source credit in `README.md` (if applicable). ## Type of Change -- [ ] New Skill -- [ ] Bug Fix +- [ ] New Skill (Feature) - [ ] Documentation Update - [ ] Infrastructure diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..513ec31 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,33 @@ +# Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information without explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1. + +[homepage]: https://www.contributor-covenant.org diff --git a/docs/QUALITY_BAR.md b/docs/QUALITY_BAR.md new file mode 100644 index 0000000..bbeb723 --- /dev/null +++ b/docs/QUALITY_BAR.md @@ -0,0 +1,64 @@ +# 🏆 Quality Bar & Validation Standards + +To transform **Antigravity Awesome Skills** from a collection of scripts into a trusted platform, every skill must meet a specific standard of quality and safety. + +## The "Validated" Badge ✅ + +A skill earns the "Validated" badge only if it passes these **5 automated checks**: + +### 1. Metadata Integrity + +The `SKILL.md` frontmatter must be valid YAML and contain: + +- `name`: Kebab-case, matches folder name. +- `description`: Under 200 chars, clear value prop. +- `risk`: One of `[none, safe, critical, offensive]`. +- `source`: URL to original source (or "self" if original). + +### 2. Clear Triggers ("When to use") + +The skill MUST have a section explicitly stating when to trigger it. + +- **Good**: "Use when the user asks to debug a React component." +- **Bad**: "This skill helps you with code." + +### 3. Safety & Risk Classification + +Every skill must declare its risk level: + +- 🟢 **none**: Pure text/reasoning (e.g., Brainstorming). +- 🔵 **safe**: Reads files, runs safe commands (e.g., Linter). +- 🟠 **critical**: Modifies state, deletes files, pushes to prod (e.g., Git Push). +- 🔴 **offensive**: Pentesting/Red Team tools. **MUST** have "Authorized Use Only" warning. + +### 4. Copy-Pasteable Examples + +At least one code block or interaction example that a user (or agent) can immediately use. + +### 5. Explicit Limitations + +A list of known edge cases or things the skill _cannot_ do. + +- _Example_: "Does not work on Windows without WSL." + +--- + +## Support Levels + +We also categorize skills by who maintains them: + +| Level | Badge | Meaning | +| :------------ | :---- | :-------------------------------------------------- | +| **Official** | 🟣 | Maintained by the core team. High reliability. | +| **Community** | ⚪ | Contributed by the ecosystem. Best effort support. | +| **Verified** | ✨ | Community skill that has passed deep manual review. | + +--- + +## How to Validate Your Skill + +Run the validator script before submitting a PR: + +```bash +python3 scripts/validate_skills.py --strict +``` diff --git a/docs/SECURITY_GUARDRAILS.md b/docs/SECURITY_GUARDRAILS.md new file mode 100644 index 0000000..feb26cf --- /dev/null +++ b/docs/SECURITY_GUARDRAILS.md @@ -0,0 +1,51 @@ +# 🛡️ Security Guardrails & Policy + +Antigravity Awesome Skills is a powerful toolkit. With great power comes great responsibility. This document defines the **Rules of Engagement** for all security and offensive capabilities in this repository. + +## 🔴 Offensive Skills Policy (The "Red Line") + +**What is an Offensive Skill?** +Any skill designed to penetrate, exploit, disrupt, or simulate attacks against systems. +_Examples: Pentesting, SQL Injection, Phishing Simulation, Red Teaming._ + +### 1. The "Authorized Use Only" Disclaimer + +Every offensive skill **MUST** begin with this exact disclaimer in its `SKILL.md`: + +> **⚠️ AUTHORIZED USE ONLY** +> This skill is for educational purposes or authorized security assessments only. +> You must have explicit, written permission from the system owner before using this tool. +> Misuse of this tool is illegal and strictly prohibited. + +### 2. Mandatory User Confirmation + +Offensive skills must **NEVER** run fully autonomously. + +- **Requirement**: The skill description/instructions must explicitly tell the agent to _ask for user confirmation_ before executing any exploit or attack command. +- **Agent Instruction**: "Ask the user to verify the target URL/IP before running." + +### 3. Safe by Design + +- **No Weaponized Payloads**: Skills should not include active malware, ransomware, or non-educational exploits. +- **Sandbox Recommended**: Instructions should recommend running in a contained environment (Docker/VM). + +--- + +## 🔵 Defensive Skills Policy + +**What is a Defensive Skill?** +Tools for hardening, auditing, monitoring, or protecting systems. +_Examples: Linting, Log Analysis, Configuration Auditing._ + +- **Data Privacy**: Defensive skills must not upload data to 3rd party servers without explicit user consent. +- **Non-Destructive**: Audits should be read-only by default. + +--- + +## ⚖️ Legal Disclaimer + +By using this repository, you agree that: + +1. You are responsible for your own actions. +2. The authors and contributors are not liable for any damage caused by these tools. +3. You will comply with all local, state, and federal laws regarding cybersecurity.