How to Contribute Your First Skill to SuperClawd Community

Have coding standards that help you write better code? Share them with the community! This guide walks you through contributing your first skill to SuperClawd.

Prerequisites

• A GitHub account
• Basic Git knowledge (fork, clone, commit, push)
• A skill you want to share (your coding guidelines, review checklist, etc.)

Step 1: Fork the Repository

Visit github.com/superclawd-ai/superclawd and click the Fork button in the top right.

This creates your own copy of the repository where you can make changes.

Step 2: Clone Your Fork

git clone https://github.com/YOUR-USERNAME/community.git
cd community

Replace YOUR-USERNAME with your GitHub username.

Step 3: Create Your Skill File

Create a JSON file in the appropriate category folder under skills/:

skills/
├── examples/
├── react/          # React-related skills
├── typescript/     # TypeScript skills
├── python/         # Python skills
└── your-category/  # Create if needed

File Naming

Use kebab-case for file names:

• react-best-practices.json
• typescript-strict-mode.json
• python-fastapi-guidelines.json

Skill Structure

Skills come in two formats: structured (instructions organized into categories) and markdown (a single free-form body). Choose "format": "structured" or "format": "markdown" — if you omit format, it defaults to structured.

Here's a complete structured example:

{
  "name": "Python FastAPI Guidelines",
  "action": "code",
  "executionMode": "auto",
  "description": "Best practices for building FastAPI applications",
  "format": "structured",
  "categories": [
    {
      "name": "Project Structure",
      "description": "How to organize FastAPI projects",
      "instructions": [
        {
          "content": "Organize routes in a routes/ directory with one file per resource",
          "type": "direct"
        },
        {
          "content": "When creating a new endpoint",
          "type": "conditional",
          "subInstructions": [
            "Use dependency injection for database sessions",
            "Add response_model for type safety",
            "Include appropriate status codes"
          ]
        }
      ]
    },
    {
      "name": "Error Handling",
      "description": "Consistent error handling patterns",
      "instructions": [
        {
          "content": "Use HTTPException for API errors with appropriate status codes",
          "type": "direct"
        },
        {
          "content": "When handling database errors",
          "type": "conditional",
          "subInstructions": [
            "Catch specific exceptions (IntegrityError, etc.)",
            "Log the full error for debugging",
            "Return a user-friendly message"
          ]
        }
      ]
    }
  ]
}

Or a markdown skill, which carries a free-form body instead of categories:

{
  "name": "Code Review Checklist",
  "action": "review",
  "executionMode": "auto",
  "description": "A checklist for thorough code reviews",
  "format": "markdown",
  "body": "# Code Review Checklist\n\n## Correctness\n- Does the change do what the PR says?\n\n## Tests\n- Is new behavior covered by tests?\n"
}

Required Fields

Instruction Types

Direct instructions always apply:

{
  "content": "Use TypeScript strict mode",
  "type": "direct"
}

Conditional instructions apply in specific situations:

{
  "content": "When writing tests",
  "type": "conditional",
  "subInstructions": [
    "Use descriptive test names",
    "Follow AAA pattern (Arrange, Act, Assert)",
    "Mock external dependencies"
  ]
}

Step 4: Test Your Skill

Before submitting, verify your skill works:

1. Go to your SuperClawd workspace
2. Navigate to Skills → Import
3. Upload your JSON file
4. Check that all categories and instructions imported correctly

Step 5: Add to the Catalog

Open skills/README.md and add your skill to the Available Skills section.

Find or create the category section and add a table row:

### Python

| Skill | Description |
|-------|-------------|
| [python-fastapi-guidelines.json](./python/python-fastapi-guidelines.json) | Best practices for FastAPI applications |

This makes your skill discoverable to others browsing the repository.

Step 6: Commit and Push

git add skills/python/python-fastapi-guidelines.json
git add skills/README.md
git commit -m "feat: add Python FastAPI guidelines skill"
git push origin main

Step 7: Create a Pull Request

1. Go to your fork on GitHub
2. Click Contribute → Open pull request
3. Add a description of your skill
4. Submit the PR

What Happens Next

1. CI runs automatically — validates your JSON schema, file naming, and catalog entry
2. We review — check for quality and usefulness
3. Feedback — we may suggest improvements
4. Merge — once approved, your skill is available to everyone!

CI Validation

Your PR must pass these checks:

If CI fails, check the error message and fix the issue.

Tips for Great Skills

Be Specific

// Too vague
"content": "Write good code"

// Better
"content": "Use descriptive variable names that indicate purpose (e.g., userCount, isValid)"

Use Conditional Instructions

Conditional instructions help the AI know when to apply guidance:

{
  "content": "When handling user input",
  "type": "conditional",
  "subInstructions": [
    "Validate all inputs before processing",
    "Sanitize strings to prevent XSS",
    "Use parameterized queries for database operations"
  ]
}

Organize Logically

Group related instructions into categories:

• Component Structure
• State Management
• Error Handling
• Testing

Keep It Focused

One skill per topic. Don't put React, TypeScript, and testing in the same skill—create separate skills.

Need Help?

• Questions? Open a Discussion
• Found an issue? Report it in Discussions
• Skill idea? Request it and someone might build it

Your Contribution Matters

Every skill you contribute helps other developers:

• Write more consistent code
• Learn best practices
• Save time building their own guidelines

Thank you for contributing to the community!

Ready to share your expertise? Visit github.com/superclawd-ai/superclawd and submit your first skill today.

Pro tip: Use coupon code WELCOME in your billing settings to get free credits when you sign up for SuperClawd!