diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4349ea6..60056a9 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -14,7 +14,7 @@ ## Skill Details (if adding a new skill) -**Provider Name:** +**Domain:** **Skill Name:** **Brief Description:** diff --git a/.github/SKILL_TEMPLATE.md b/.github/SKILL_TEMPLATE.md index 8a652db..d4c9ca7 100644 --- a/.github/SKILL_TEMPLATE.md +++ b/.github/SKILL_TEMPLATE.md @@ -1,97 +1,40 @@ # Skill Template -Use this template when creating a new `SKILL.md` file for your skill. +Copy the block below into `domains//skills//skill.md` and replace the placeholders. See [Authoring a skill](../README.md#authoring-a-skill) for the canonical layout and the full frontmatter schema. --- -# [Skill Name] - -> Brief one-line description of what this skill does. - -## Overview - -A more detailed explanation of the skill's purpose and capabilities. What problem does it solve? Who is it for? - -## Prerequisites - -List any requirements before using this skill: - -- Required tools (e.g., Node.js, Python, specific CLI tools) -- Required API keys or environment variables -- Required knowledge or context - -## Instructions - -Provide clear, step-by-step instructions for the AI agent to follow. - -### Step 1: [Action Name] - -Detailed instructions for the first step. - -```bash -# Example command if applicable -example-command --flag value -``` +```markdown +--- +name: +description: +maturity: experimental +--- -### Step 2: [Action Name] +# -Detailed instructions for the second step. +## When To Use -### Step 3: [Action Name] +- +- -Continue with additional steps as needed. +## Workflow -## Examples +1. **.** State what the agent should do and how to tell it is done. +2. **.** Keep steps imperative and verifiable. +3. **.** Reference supporting material in `references/` rather than inlining long content. -### Example 1: [Use Case Name] +## Common Pitfalls +| Pitfall | Rule | +|---|---| +| | | +| | | ``` -User: "Help me [do something specific]" -Agent: [Expected behavior or response] -``` - -### Example 2: [Another Use Case] - -Provide additional examples to clarify usage. - -## Configuration - -If the skill requires configuration, document it here: - -| Parameter | Type | Required | Default | Description | -|-----------|------|----------|---------|-------------| -| `param1` | string | Yes | — | Description of param1 | -| `param2` | number | No | `10` | Description of param2 | - -## Troubleshooting - -### Common Issue 1 - -**Problem:** Description of the issue. - -**Solution:** How to resolve it. - -### Common Issue 2 - -**Problem:** Another common issue. - -**Solution:** Resolution steps. - -## Security Considerations - -Document any security implications: - -- What permissions does this skill require? -- Are there any risks users should be aware of? -- What data is accessed or transmitted? - -## References - -- [Link to official documentation](https://example.com) -- [Link to related resources](https://example.com) -## Changelog +## Notes for authors -| Version | Date | Changes | -|---------|------|---------| -| 1.0.0 | YYYY-MM-DD | Initial release | +- Keep `name` unprefixed and matching the skill's directory name. The installer adds the `mms-` prefix to the generated outputs. +- `maturity` is optional and defaults to `stable`. Use `experimental` for new skills and `deprecated` on the way out. +- Put supporting docs in `references/`, which the skill reads on demand, rather than expanding the description. The description is always loaded into the agent's discovery surface, while the body and references are not. +- Add a `repos/.md` overlay only when a consuming repo needs repo-specific guidance. It is merged into the skill body at install time. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0331d4e..06a58e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,8 +21,8 @@ A well-crafted skill should: 1. **Fork and clone** the repository: ```bash - git clone https://github.com/YOUR_USERNAME/openclaw-skills.git - cd openclaw-skills + git clone https://github.com/MetaMask/skills.git + cd skills ``` 2. **Create a branch** for your skill: @@ -30,16 +30,17 @@ A well-crafted skill should: git checkout -b add-skill/your-skill-name ``` -3. **Create the skill directory structure**: +3. **Create the skill directory** under the relevant domain: ```bash - mkdir -p your-provider/your-skill-name + mkdir -p domains//skills/ ``` -4. **Add your `SKILL.md`** — This is the only required file. See the [skill template](.github/SKILL_TEMPLATE.md) for the expected format. +4. **Add your `skill.md`** — This is the only required file. See [Authoring a skill](README.md#authoring-a-skill) for the canonical layout and frontmatter, and the [skill template](.github/SKILL_TEMPLATE.md) for a starting point. -5. **Add optional supporting files**: - - `references/` — Additional documentation, API references, examples - - `scripts/` — Helper scripts (bash, Python, etc.) +5. **Add optional supporting files** alongside `skill.md`: + - `references/` — supporting docs the skill reads on demand + - `scripts/` — helper scripts the skill can run + - `repos/.md` — a per-repo overlay merged into the skill body at install time 6. **Test your skill** — Ensure the skill works as expected with an AI agent before submitting. @@ -68,28 +69,32 @@ If you find a bug or have a suggestion: ## Skill Structure -Each skill should follow this structure: +Each skill lives under a domain and follows this structure: ``` -provider-name/ -└── skill-name/ - ├── SKILL.md # Required: Main skill definition - ├── references/ # Optional: Supporting docs +domains// +└── skills// + ├── skill.md # Required: the skill definition + ├── references/ # Optional: supporting docs read on demand │ ├── api.md │ └── examples.md - └── scripts/ # Optional: Helper scripts - └── helper.sh + ├── scripts/ # Optional: helper scripts + │ └── helper.sh + └── repos/ # Optional: per-repo overlays + └── metamask-extension.md ``` -### SKILL.md Format +See [Authoring a skill](README.md#authoring-a-skill) for the canonical layout and the frontmatter schema. -Your `SKILL.md` should include: +### `skill.md` format -1. **Title and description** — What the skill does -2. **Prerequisites** — Required tools, APIs, or setup -3. **Instructions** — Step-by-step guidance for the AI agent -4. **Examples** — Concrete usage examples -5. **Troubleshooting** — Common issues and solutions +Each `skill.md` begins with YAML frontmatter (`name`, `description`, and optional `maturity`), documented in full under [Authoring a skill](README.md#authoring-a-skill). The body should give the agent everything it needs to act: + +1. **When To Use** — the conditions that should trigger the skill +2. **Workflow** — the step-by-step procedure for the agent to follow +3. **Common Pitfalls** — known failure modes, each paired with the rule that avoids it + +Keep `name` unprefixed in the source file. The installer adds the `mms-` prefix to generated outputs. ## Review Process