From dbfe8f31f01bbbc78922691394e6d59606cca7af Mon Sep 17 00:00:00 2001 From: Harjun751 Date: Fri, 30 Jan 2026 17:17:56 +0800 Subject: [PATCH 1/4] Add update-docs skill --- .github/skills/update-docs/SKILL.md | 52 +++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 .github/skills/update-docs/SKILL.md diff --git a/.github/skills/update-docs/SKILL.md b/.github/skills/update-docs/SKILL.md new file mode 100644 index 0000000000..6f1ca9c233 --- /dev/null +++ b/.github/skills/update-docs/SKILL.md @@ -0,0 +1,52 @@ +--- +name: update-docs +description: > + Update user or developer documentation only if the change is relevant to the specific purpose of the documentation. + Use when editing files within the `docs/` folder. +--- + +# Updating Documentation + +You are a pragmatic senior developer who is particular about maintaining concise but useful & relevant documentation. +Follow this workflow to ensure documentation updates are relevant and purposeful. + +## 1. Determine Documentation Purpose +Identify the **goal** of the documentation you are updating: +- **User Documentation**: Focuses on how to use the project (features, APIs, workflows, examples). +- **Developer Documentation**: Focuses on how to contribute to the project (architecture, internals, build processes, dependencies). + +## 2. Assess Change Relevance +For each change, evaluate its relevance based on the documentation type: + +| Change Type | User Documentation | Developer Documentation | +|---------------------------|----------------------------------------|----------------------------| +| New feature | ✅ Update (usage, examples) | ✅ Update (implementation) | +| Breaking change | ✅ Update (migration notes) | ✅ Update (code changes) | +| Bug fix | ✅ Update if user-facing | ✅ Update if relevant | +| Dependency bump | ❌ Skip | ❌ Skip | +| Internal refactor | ❌ Skip | ✅ Only if affects workflow | + +## 3. Review Changes +- Use `git diff $(git merge-base --fork-point master)` to view changes. +- If a specific base commit SHA is provided, use `git diff ${SHA}`. +- Check commit messages for extra context + +## 4. Update Documentation +- **User Documentation**: Focus on what users need to know (e.g., new features, deprecated functionality). +- **Developer Documentation**: Focus on what developers need to know (e.g., new build steps, architecture changes). + +## 5. Diagrams and Visuals +- Add/update **Mermaid diagrams** if the change affects workflows, architecture, or user/developer processes. +- For static diagrams (e.g., `.png`), flag for manual review if the change alters the visualized concept. + +## 6. Rules for Packages/Dependencies +- **User Documentation**: Only mention packages if they are part of the public interface (e.g., "This project requires Docker 20.10+"). +- **Developer Documentation**: List packages only if they are critical to the build/development process (e.g., "Use Node.js 18+"). + +## 7. Automation Tips +- Pre-filter changes using scripts (e.g., ignore `package.json` updates unless they include `BREAKING CHANGE` or `feat`). +- Flag ambiguous cases for manual review (e.g., "This change might affect the 'Configuration' section—please verify"). + +## 8. Key Question for LLM +Before updating, ask: +*"Does this change directly impact the audience (users or developers) of the documentation I’m editing? If not, skip it."* From a82bd2abee397130fd4baf4813010610ad94b4d8 Mon Sep 17 00:00:00 2001 From: Harjun751 Date: Fri, 30 Jan 2026 17:44:19 +0800 Subject: [PATCH 2/4] Update skill to use predefined script --- .github/skills/update-docs/SKILL.md | 23 +- .github/skills/update-docs/docs/RULES.md | 356 ++++++++++++++++++ .../skills/update-docs/scripts/get-diff.sh | 15 + 3 files changed, 387 insertions(+), 7 deletions(-) create mode 100644 .github/skills/update-docs/docs/RULES.md create mode 100644 .github/skills/update-docs/scripts/get-diff.sh diff --git a/.github/skills/update-docs/SKILL.md b/.github/skills/update-docs/SKILL.md index 6f1ca9c233..5ea4ea3fdc 100644 --- a/.github/skills/update-docs/SKILL.md +++ b/.github/skills/update-docs/SKILL.md @@ -27,14 +27,27 @@ For each change, evaluate its relevance based on the documentation type: | Internal refactor | ❌ Skip | ✅ Only if affects workflow | ## 3. Review Changes -- Use `git diff $(git merge-base --fork-point master)` to view changes. -- If a specific base commit SHA is provided, use `git diff ${SHA}`. -- Check commit messages for extra context +Use ONLY the following to obtain the changelog: +```bash +bash /mnt/skills/user/update-docs/scripts/get-diff.sh [arg1] +``` +Arguments: +- `arg1` - Optional argument that should be used when a specific SHA is specifically supplied. + +Output: +The git diff and relevant changes to review. + +## 4. Key Questions for LLM pre-review +Before updating, ask: +- *"Does this change directly impact the audience (users or developers) of the documentation I’m editing? If not, skip it."* +- *"Am I unsure of any part of the update I'm making? If so, I must clarify before proceeding."* ## 4. Update Documentation - **User Documentation**: Focus on what users need to know (e.g., new features, deprecated functionality). - **Developer Documentation**: Focus on what developers need to know (e.g., new build steps, architecture changes). +When updating documentation, keep in mind the rules specified in [RULES.md](docs/RULES.md) + ## 5. Diagrams and Visuals - Add/update **Mermaid diagrams** if the change affects workflows, architecture, or user/developer processes. - For static diagrams (e.g., `.png`), flag for manual review if the change alters the visualized concept. @@ -46,7 +59,3 @@ For each change, evaluate its relevance based on the documentation type: ## 7. Automation Tips - Pre-filter changes using scripts (e.g., ignore `package.json` updates unless they include `BREAKING CHANGE` or `feat`). - Flag ambiguous cases for manual review (e.g., "This change might affect the 'Configuration' section—please verify"). - -## 8. Key Question for LLM -Before updating, ask: -*"Does this change directly impact the audience (users or developers) of the documentation I’m editing? If not, skip it."* diff --git a/.github/skills/update-docs/docs/RULES.md b/.github/skills/update-docs/docs/RULES.md new file mode 100644 index 0000000000..4b768d6e90 --- /dev/null +++ b/.github/skills/update-docs/docs/RULES.md @@ -0,0 +1,356 @@ +# MarkBind Documentation Rules and Best Practices + +## Basic Rules + +### 1. Frontmatter Usage +All documentation files must start with a frontmatter section containing at least a title. + +```markdown + + title: "Page Title" + +``` + +Some files may include additional metadata like layout, pageNav, etc. + +### 2. Lead Placement +Lead text (introductory text) should only appear at the top of pages, typically right after the main heading. + +```markdown +

**Main Title**

+ +Introductory lead text goes here. +``` + +### 3. Environment Tags +Use environment tags to control content visibility across different documentation environments: + +- `environment--ug` for User Guide content +- `environment--dg` for Developer Guide content +- `environment--combined` for both environments + +```markdown +
+ +
+ +
+ +
+``` + +### 4. MarkBind Text Formatting Syntax + +#### Highlighted Text +```markdown +==highlighted text== +``` + +#### Grey/Dimmed Text +```markdown +%%grey text%% +``` + +#### Underlined Text +```markdown +!!underlined text!! +``` + +#### Strikethrough Text +```markdown +~~strikethrough text~~ +``` + +#### Bold and Italic +```markdown +**bold text** +_italic text_ +___bold and italic___ +``` + +### 5. Tooltips +Use tooltips for inline explanations and definitions: + +```markdown +trigger text +``` + +Examples: +```markdown +CS +nvm +_more dynamic_ +``` + +Tooltip placement options: +```markdown +trigger +``` + +### 6. Popovers and Modals +Use triggers with popovers and modals for interactive content: + +```markdown +trigger text + +
+ Popover content here +
+ + +trigger text + + Modal content here + +``` + +### 7. Content Reuse with Includes +Use the include mechanism to avoid duplication and maintain consistency: + +```markdown + + value + +``` + +## Consistent Formatting Rules + +### 1. Text Styles +Maintain consistent use of MarkBind text formatting throughout documentation: + +- `**bold**` and `_italic_` for emphasis +- `==highlighted text==` for important concepts +- `%%dimmed text%%` for secondary information +- `!!underlined text!!` for interactive elements +- `~~strikethrough~~` for deprecated or removed content + +### 2. Code Examples +Use consistent code formatting with proper syntax highlighting: + +```markdown +```html +trigger +``` + +For code and output examples: +```markdown + + markdown + + Example code here + + +``` + +### 3. Panels and Boxes +Organize content using panels and boxes: + +```markdown + + Panel content here + + + + Grouped content here + +``` + +Panel types: +- `seamless` - no border, blends with page +- `primary`, `secondary`, `success`, `danger`, `warning`, `info` - colored panels +- Custom headers with `%%text%%` formatting + +### 4. Lists and Tables +Use proper Markdown formatting for lists and tables: + +```markdown +- List item 1 +- List item 2 + - Nested item + +1. Numbered item 1 +2. Numbered item 2 + +Syntax | Code | Output +-------|------|------- +Markdown | `**bold**` | **bold** +``` + +### 5. Cross-referencing +Link to other documentation sections using relative paths: + +```markdown +[link text](userGuide/formattingContents.html) +[link text](userGuide/formattingContents.html#section-id) +``` + +### 6. Environment-Specific Content +Wrap environment-specific content appropriately: + +```markdown +
+ +
+ +
+ +
+``` + +## Best Practices + +### 1. Interactive Elements +Use tooltips, popovers, and modals judiciously: +- Tooltips for brief explanations and definitions +- Popovers for slightly more detailed information +- Modals for complex or lengthy content that shouldn't interrupt main flow + +### 2. Content Organization +Use panels, boxes, and tabs to organize related content logically: + +```markdown + + + Content for tab 1 + + + Content for tab 2 + + +``` + +### 3. Version Information +Include version-specific details, especially for installation and update instructions: + +```markdown +[Node.js](https://nodejs.org) {{ node_version }} or higher installed +``` + +### 4. Prerequisites +Clearly list prerequisites at the beginning of guides: + +```markdown +++**Prerequisites**++ + +
+ %%{{ icon_ticked }}%% Requirement 1 + %%{{ icon_ticked }}%% Requirement 2 +
+``` + +### 5. Step-by-Step Instructions +Provide clear, numbered steps with appropriate code examples: + +```markdown +++**1. Step Title**++ + +Instruction text here + +``` +code example here +``` + +++**2. Next Step**++ + +More instructions +``` + +### 6. Contributor Sections +Maintain the ALL-CONTRIBUTORS-LIST format without modification: + +```markdown + + + + + +
+ + + +``` + +### 7. 404 Page Format +Use the specific arrow syntax for 404 pages: + +```markdown +->

404

<- +->

File not found
Click here to go back to the home page.

<- +``` + +### 8. Icons and Emoji +Use consistent icon and emoji formatting: + +```markdown +:glyphicon-icon-name: +:fa-solid-icon-name: +:fa-brands-icon-name: +:emoji-shortcode: +``` + +### 9. Variables and Templates +Use variables for consistent values across documentation: + +```markdown +{% set title = "Page Title" %} +{{ title }} +``` + +### 10. Comments and Annotations +Use proper comment formatting: + +```markdown + + +{% comment %} +Multi-line +comment block +{% endcomment %} + +%%Comment that appears in output%% +``` + +## File Structure and Organization + +### Frontmatter Requirements +- All `.md` files should have frontmatter with at least `title` +- User guide files should include `layout: userGuide.md` +- Developer guide files should include `layout: devGuide.md` + +### Directory Structure +- `docs/` - Main documentation root +- `docs/userGuide/` - User guide content +- `docs/devGuide/` - Developer guide content +- `docs/_markbind/` - Templates and boilerplates +- `docs/pages/` - Reusable content fragments + +### Configuration Files +- `site.json` - Main site configuration +- `ug-site.json` - User guide specific configuration +- `dg-site.json` - Developer guide specific configuration + +## Writing Style Guidelines + +1. **Concise Language**: Use clear, direct language suitable for an LLM audience +2. **Consistent Terminology**: Use established MarkBind terminology consistently +3. **Logical Flow**: Organize content from basic to advanced concepts +4. **Practical Examples**: Include relevant examples for each concept +5. **Cross-references**: Link to related documentation sections +6. **Version Awareness**: Note version-specific behaviors and requirements + +## Navigation Rules + +### Previous/Next Configuration + +When adding or modifying navigation links in the documentation, ensure that the `previous_next` configuration is updated to maintain proper navigation flow. Specifically: + +- The "previous" link of the page that comes after the new page should point to the new page. +- The "next" link of the page that comes before the new page should point to the new page. + +This ensures that users can navigate through the documentation seamlessly without encountering broken links or incorrect navigation paths. + +**Example**: +```markdown +{% from "njk/common.njk" import previous_next %} +{{ previous_next('previousPage', 'nextPage') }} +``` diff --git a/.github/skills/update-docs/scripts/get-diff.sh b/.github/skills/update-docs/scripts/get-diff.sh new file mode 100644 index 0000000000..edd6f82299 --- /dev/null +++ b/.github/skills/update-docs/scripts/get-diff.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +# Git diff script that supports optional base commit SHA parameter +# Usage: ./get-diff.sh [COMMIT_SHA] + +# Check if a commit SHA parameter is provided +if [ $# -eq 1 ]; then + # Use the provided commit SHA + echo "Showing diff from commit: $1" + git diff "$1" +else + # Use the default: diff from fork point with master + echo "Showing diff from fork point with master" + git diff $(git merge-base --fork-point master) +fi From 53f7091e0a4bca2ec8d2f40bad9c1061a89df9b0 Mon Sep 17 00:00:00 2001 From: Harjun751 Date: Fri, 30 Jan 2026 19:08:39 +0800 Subject: [PATCH 3/4] Update dev docs to mention skills and usage --- docs/_markbind/layouts/devGuide.md | 1 + docs/devGuide/development/skills.md | 51 +++++++++++++++++++ docs/devGuide/development/workflow.md | 9 +++- .../devGuide/development/writingComponents.md | 2 +- 4 files changed, 61 insertions(+), 2 deletions(-) create mode 100644 docs/devGuide/development/skills.md diff --git a/docs/_markbind/layouts/devGuide.md b/docs/_markbind/layouts/devGuide.md index 64e9e4cbb2..c826049108 100644 --- a/docs/_markbind/layouts/devGuide.md +++ b/docs/_markbind/layouts/devGuide.md @@ -17,6 +17,7 @@ * Development :expanded: * [Setting up]({{baseUrl}}/devGuide/development/settingUp.html) * [Workflow]({{baseUrl}}/devGuide/development/workflow.html) + * [Skills]({{baseUrl}}/devGuide/development/skills.html) * [Writing Components]({{baseUrl}}/devGuide/development/writingComponents.html) * [Writing Plugins]({{baseUrl}}/devGuide/development/writingPlugins.html) * [Migrating to TypeScript]({{baseUrl}}/devGuide/development/migratingToTypeScript.html) diff --git a/docs/devGuide/development/skills.md b/docs/devGuide/development/skills.md new file mode 100644 index 0000000000..06080d4ef4 --- /dev/null +++ b/docs/devGuide/development/skills.md @@ -0,0 +1,51 @@ +{% set title = "Skills" %} +{{ title }} + + + title: "{{ title }}" + layout: devGuide.md + pageNav: default + + +# {{ title }} + +
+ +Skills are directories containing instructions, scripts, and resources that AI agents dynamically load to handle specific tasks. Each skill has a `SKILL.md` file that defines when it should be activated and what instructions the AI agent should follow. +
+ +## Overview + +Skills are designed to improve AI agent performance by providing structured instructions and resources for specific tasks. This is applicable to any AI agent with skill support, and developers can point AI agents to the skills directory for structured task handling. + +## Skills Directory + +Skills are located in the `.github/skills/` directory. You can point AI agents to this directory to leverage the structured instructions and resources provided by the skills. + +## List of Skills + +The following skills are available in the MarkBind project: + +| Skill Name | Description | +|------------|-------------| +| `update-docs` | Update user or developer documentation only if the change is relevant to the specific purpose of the documentation. Use when editing files within the `docs/` folder. | + +## Adding New Skills + +If you find yourself performing similar structured tasks with an AI agent, consider adding a new skill to the `.github/skills/` directory. Each skill should include: + +1. A `SKILL.md` file that defines the skill's purpose, when it should be activated, and what instructions the AI agent should follow. +2. Any necessary scripts or resources to support the skill's functionality. +3. Clear documentation on how to use the skill. + +## Using Skills + +Skills relevant to particular tasks should be invoked automatically by AI agents. You may opt to directly point the agent to a skill. + +## Useful Links +- [Skill.sh skill repository](https://skills.sh/) +- [Cline reference on skills & writing them](https://docs.cline.bot/features/skills) +- [Claude reference on skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) + +{% from "njk/common.njk" import previous_next %} +{{ previous_next('workflow', 'writingComponents') }} diff --git a/docs/devGuide/development/workflow.md b/docs/devGuide/development/workflow.md index 705028b724..fedaff7554 100644 --- a/docs/devGuide/development/workflow.md +++ b/docs/devGuide/development/workflow.md @@ -419,5 +419,12 @@ To update PlantUML to a newer version: As Bootswatch is built on Bootstrap, ensure that the versions of both are in sync to avoid unexpected differences in styling behavior between default and other themes. Both are currently using version 5.1.3. +## Using Skills +As a developer, you may use AI in your workflow to perform tasks. If a specific task is done repeatedly, you may leverage Skills to improve AI output and save time. + +Skills are invoked whenever an agent detects a task to be relevant to one, though sometimes manual pointing may be necessary. + +MarkBind houses several skills that you may find useful. See the [Skills](./skills.md) page for a full list and more information. + {% from "njk/common.njk" import previous_next %} -{{ previous_next('settingUp', 'writingComponents') }} +{{ previous_next('settingUp', 'skills') }} diff --git a/docs/devGuide/development/writingComponents.md b/docs/devGuide/development/writingComponents.md index b2ba4469f8..32d64652fe 100644 --- a/docs/devGuide/development/writingComponents.md +++ b/docs/devGuide/development/writingComponents.md @@ -153,4 +153,4 @@ MarkBind should also **log a warning** to inform the author of this conflict! {% from "njk/common.njk" import previous_next %} -{{ previous_next('workflow', 'writingPlugins') }} \ No newline at end of file +{{ previous_next('skills', 'writingPlugins') }} From 36835d295fb669335aec10ab9adc4a2c0762ac3c Mon Sep 17 00:00:00 2001 From: Harjun751 Date: Sun, 1 Feb 2026 20:34:21 +0800 Subject: [PATCH 4/4] Minor rule tweak for clarity --- .github/skills/update-docs/docs/RULES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/skills/update-docs/docs/RULES.md b/.github/skills/update-docs/docs/RULES.md index 4b768d6e90..1efb2de009 100644 --- a/.github/skills/update-docs/docs/RULES.md +++ b/.github/skills/update-docs/docs/RULES.md @@ -337,6 +337,7 @@ comment block 4. **Practical Examples**: Include relevant examples for each concept 5. **Cross-references**: Link to related documentation sections 6. **Version Awareness**: Note version-specific behaviors and requirements +7. **Timelessness and clarity**: Avoid using phrasies like "now supports". Communicate about the product in the current state and be clear. ## Navigation Rules