Skip to content

gapmiss/obsidian-plugin-skill / .agents/skills/obsidian

obsidian

Verified

Comprehensive guidelines for Obsidian.md plugin development including ESLint rules from eslint-plugin-obsidianmd v0.6.0, TypeScript best practices, memory management, API usage (requestUrl vs fetch), UI/UX standards, popout window compatibility, community.obsidian.md submission process, and Scorecard optimization. Use when working with Obsidian plugins, main.ts files, manifest.json, Plugin class, MarkdownView, TFile, vault operations, or any Obsidian API development.

reference/submission.md

View on GitHub
# Plugin Submission Requirements

Guidelines for publishing your plugin to the Obsidian community plugin directory.

## Repository Structure

```
your-plugin/
├── manifest.json       # Required: Plugin metadata
├── main.js            # Required: Compiled plugin code
├── styles.css         # Optional: Plugin styles
├── LICENSE            # Required: License file
└── README.md          # Recommended: Usage documentation
```

---

## Naming and Description Guidelines

These rules come from the developer docs' manifest reference and the community review. `obsidianmd/validate-manifest` (v0.6.0) checks them locally on `manifest.json` (the `id` rules only with `checkId: true` — turn it on before your first submission) — run `npx eslint .` from the project root to catch them before submitting:

### Plugin ID (Required)
- **Cannot contain "obsidian"** (case-insensitive)
- **Cannot end with "plugin"** ("plugin" elsewhere in the id is fine)
- **Must use only**: lowercase alphanumeric characters, dashes (`-`), and underscores (`_`)
- Must be unique (not used by existing or removed plugins)
- Keep it short and simple (used for plugin folder name)

### Plugin Name (Required)
- **Cannot contain "Obsidian"** (case-insensitive)
- **Cannot contain "Plugin"** anywhere
- **Cannot contain parts of "Obsidian"**: "obsi", "sidian", or a leading "ob"
- Must be unique among existing plugins
- Use a clear, descriptive name

### Description (Required)
- **Cannot include "Obsidian"** (case-insensitive)
- **Cannot refer to itself**: "This plugin", "This tool", "This extension", "A plugin that/for/to", "The plugin …"
- **Must end with punctuation**: `.`, `!`, or `?` (a closing `)` is not accepted)
- **10–250 characters**
- **Cannot be the same as, or start with, the plugin name**
- A lowercase first letter, emoji, and mentioning plugins in general ("Reload plugins in development.") are fine
- Focus on what the plugin does, not what it is

### Author (Required)
- Must be the repository owner or a public member of the organization
- Repository must have issues enabled (warning)
- Must include a valid open source license

### Repository (Required)
- Format: `"owner/repo-name"`
- Must match the actual GitHub repository

### Manifest Synchronization
- Plugin `id`, `name`, and `description` must match `manifest.json` in the repository

---

**Examples:**

✅ Good:
```json
{
  "id": "daily-notes-helper",
  "name": "Daily Notes Helper",
  "description": "Enhance your daily notes workflow with templates and quick actions.",
  "author": "YourUsername",
  "repo": "YourUsername/daily-notes-helper"
}
```

❌ Bad:
```json
{
  "id": "obsidian-daily-notes-plugin",  // Contains "obsidian" and ends with "plugin"
  "name": "Obsidian Daily Notes Plugin", // Contains "Obsidian" and "Plugin"
  "description": "This is an Obsidian plugin that helps with daily notes" // Contains "Obsidian", refers to itself ("an ... plugin that"), no punctuation
}
```

---

## Submission Process

### 1. Create GitHub Release

- Tag must match version in `manifest.json` (e.g., `1.0.0`)
- Attach binary assets: `main.js`, `manifest.json`, `styles.css` (optional)
- Consider adding GitHub artifact attestation for better Scorecard

### 2. Submit via community.obsidian.md

1. Sign in at **community.obsidian.md**
2. Link your GitHub account to your Obsidian profile
3. Navigate to **Plugins → New plugin**
4. Enter your repository URL
5. Review Developer policies and confirm support commitment
6. Submit for review

### 3. Address Feedback

- Automated review provides guidance on required corrections
- Update your repository and publish a new release with incremented version
- The directory processes `manifest.json` from your repository's default branch

### 4. Follow Developer Policies

- Comply with Obsidian's terms of service
- No malicious code
- Respect user privacy
- No analytics without disclosure

---

## Semantic Versioning

Follow semantic versioning:
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes

---

## Testing Before Submission

- Test on mobile (if not desktop-only)
- Test with keyboard navigation
- Test in both light and dark themes
- Verify all ESLint rules pass (errors AND warnings)
- Remove all sample/template code
- Ensure manifest.json is valid
- Include LICENSE file

### Declarative Settings Verification (1.13+)

If your plugin uses `getSettingDefinitions()`:
- Walk the settings tab top to bottom — every setting renders and reflects the current value
- Changes persist across a reload
- Global settings search finds each setting by name (and `aliases`, if set)
- For each `validate` callback, enter invalid input — inline error appears, value is not saved
- For any `type: 'list'` groups, add/delete/reorder rows — `plugin.settings` updates correctly
- For any sub-pages, navigate in and back
- If using Path B (dual support), test on an Obsidian version below 1.13.0 to verify `display()` still works

---

## Scorecard System

Published plugins receive a **Scorecard** on community.obsidian.md that users see when browsing. Scorecard mechanics (Overall Score, Health metrics, Review checks, Disclosures, and improvement tips) are documented in [community-scanner.md](community-scanner.md#scorecard-system).
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall