mirror of
https://github.com/InsForge/insforge-skills.git
synced 2026-09-14 16:03:59 +08:00
yaowenc2
8c72c09c49
Codex's bundled skill-creator spec (references/openai_yaml.md) requires default_prompt to reference the skill explicitly as $skill-name. Also document the interface field set and constraints in CONTRIBUTING.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QT8v1kqCZYreDZwy6wfzJH
99 lines
2.9 KiB
Markdown
99 lines
2.9 KiB
Markdown
# 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](https://agentskills.io/). Please review the specification before contributing.
|
|
|
|
### SKILL.md Requirements
|
|
|
|
Every skill must have a `SKILL.md` file with:
|
|
|
|
```yaml
|
|
---
|
|
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
|
|
|
|
```javascript
|
|
// 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.
|