From e379a650c7eac9c7486d18c1d98691c90c5469e0 Mon Sep 17 00:00:00 2001 From: Jongsun Suh Date: Tue, 9 Jun 2026 14:33:25 -0400 Subject: [PATCH] docs: align contribution docs with real skill layout CONTRIBUTING.md, SKILL_TEMPLATE.md, and the PR template described a provider-name/SKILL.md structure that does not exist in this repo. Skills actually live at domains//skills//skill.md with name/description/ maturity frontmatter, documented in the README 'Authoring a skill' section. Reconcile the contribution docs to that layout and point to the README as the single source for the frontmatter schema rather than restating it. Fix the clone URL and the 'Provider Name' PR-template field. --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/SKILL_TEMPLATE.md | 107 ++++++++----------------------- CONTRIBUTING.md | 49 +++++++------- 3 files changed, 53 insertions(+), 105 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4349ea65..60056a99 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 8a652db3..d4c9ca7f 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 0331d4e3..06a58e29 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