insforge__insforge-skills/CONTRIBUTING.md

Contributing to InsForge Agent Skills

Thank you for your interest in contributing to InsForge Agent Skills! This document provides guidelines for contributing to this repository.

Getting Started

1. Fork this repository
2. Clone your fork locally
3. Create a branch for your changes

Skill Format

This repository follows the Agent Skills Open Standard. Please review the specification before contributing.

SKILL.md Requirements

Every skill must have a SKILL.md file with:

---
name: skill-name           # Required: lowercase, hyphens only, matches directory name
description: |             # Required: clear description of what the skill does
  Description here...
license: Apache-2.0        # Optional: license identifier
---

# Skill content in Markdown...

Do not add a metadata: block to the frontmatter — the OpenAI plugin submission portal rejects skills that carry one. User-facing interface settings (display name, short description, brand color, default prompt) belong in the skill's agents/openai.yaml under interface: instead. Keep short_description between 25 and 64 characters, and have default_prompt reference the skill as $skill-name.

Documentation Files

For InsForge modules, keep documentation focused on the app or platform surface being used:

• sdk-integration.md: Client-side SDK usage with @insforge/sdk
• Specialized guides: Backend, security, protocol, or workflow-specific references such as RLS, pgvector, S3-compatible storage, or capability guides

Documentation Guidelines

Structure

Each documentation file should include:

1. Title and Overview: Brief description of the module
2. Setup/Prerequisites: Required configuration or imports
3. Usage Examples: Practical code examples
4. Best Practices: Recommended patterns
5. Common Mistakes: What to avoid with solutions

Code Examples

• Keep examples concise and runnable
• Use consistent formatting
• Include both correct and incorrect examples where helpful
• Show the { data, error } return pattern

// Good: Shows complete pattern
const { data, error } = await insforge.database.from('posts').select()
if (error) {
  console.error(error)
  return
}
console.log(data)

Writing Style

• Use clear, direct language
• Prefer active voice
• Keep explanations brief
• Use tables for reference information

Adding a New Module

1. Create a directory under skills/insforge/
2. Add the required documentation files
3. Update the module reference table in skills/insforge/SKILL.md
4. Test that all links work correctly

Pull Request Process

1. Ensure your changes follow the format guidelines
2. Update relevant documentation if adding features
3. Submit a pull request with a clear description
4. Respond to any feedback from reviewers

Questions?

If you have questions about contributing, please open an issue for discussion.