gapmiss/obsidian-plugin-skill / .agents/skills/obsidian
obsidian
VerifiedComprehensive 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.0 KB |
| reference/accessibility.md | markdown | 8.0 KB |
| reference/code-quality.md | markdown | 21.9 KB |
| reference/community-scanner.md | markdown | 10.8 KB |
| reference/css-styling.md | markdown | 10.7 KB |
| reference/eslint-setup.md | markdown | 72.3 KB |
| reference/file-operations.md | markdown | 6.1 KB |
| reference/memory-management.md | markdown | 6.3 KB |
| reference/submission.md | markdown | 5.2 KB |
| reference/type-safety.md | markdown | 1.5 KB |
| reference/ui-ux.md | markdown | 29.0 KB |
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).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |