polardbx-skills
AGENTS.md8 starsChanged 28 days agoApache-2.0View on GitHub
Follow this section order (see polardbx-sql/SKILL.md as the reference example): Key principle: SKILL.md must contain enough inline knowledge for the agent to handle common questions without reading references. References are for deep dives, not the primary source.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository11 other files it gives its agents.
- polardbx-cciSkill
- polardbx-cclSkill
- polardbx-online-ddlSkill
- polardbx-opsSkill
- polardbx-paginationSkill
- polardbx-plan-analysisSkill
- polardbx-sqlSkill
- polardbx-standardSkill
- polardbx-ttl20Skill
- polardbx-zeroSkill
- sql-reviewSkill
The file
We split this AGENTS.md into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 6
Every skill must have a SKILL.md with YAML frontmatter (name + description).
- Very specific: line 8
Follow the skills.sh specification.
- Very specific: line 12
Follow this section order (see polardbx-sql/SKILL.md as the reference example):
- Very specific: line 27
Write description, instructions, and core logic in English — LLMs follow English instructions more reliably.
- Very specific: line 28
Write triggers in both English and Chinese to cover different user input habits.
- Distinctive: line 29
Write output templates in the target user's language.
- Distinctive: line 30
Keep language consistent within each paragraph — do not mix languages mid-paragraph.
- Very specific: line 34
Every SKILL.md has a metadata.version field in YAML frontmatter (semver).
- Distinctive: line 39
When adding, removing, or renaming a skill, update README.md accordingly:
- Distinctive: line 40
Update the directory tree in the "目录结构" section.
- Distinctive: line 41
Update the skill list in the "当前 Skills" section (one-line description per skill).
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill Writing Guidelines
Directory & File Structure
- Directory names: lowercase, digits, hyphens (e.g.
polardbx-sql). - Every skill must have a
SKILL.mdwith YAML frontmatter (name+description). - Detailed docs go in
references/, executable scripts inscripts/, playbooks inplaybooks/. - Follow the skills.sh specification.
SKILL.md Structure
Follow this section order (see polardbx-sql/SKILL.md as the reference example):
- Frontmatter:
name(kebab-case, matches directory),description(what it does + when to use + triggers, < 1024 chars),metadata.version. - Title + one-line summary: What the skill does.
- Scope: What it applies to and what it does NOT apply to, with verification commands.
- Core Workflow: Numbered steps the agent follows every time.
- Key Features / Differences Quick Reference: Inline knowledge the agent can use without reading references — include key SQL commands, critical syntax, and common pitfalls.
- Best Practices (if applicable): Numbered actionable recommendations.
- References: Table format, relative paths.
| [references/xxx.md](references/xxx.md) | Description | - Playbooks (if applicable): Table format, relative paths.
Key principle: SKILL.md must contain enough inline knowledge for the agent to handle common questions without reading references. References are for deep dives, not the primary source.
Language
- Write
description,instructions, and core logic in English — LLMs follow English instructions more reliably. - Write
triggersin both English and Chinese to cover different user input habits. - Write output templates in the target user's language.
- Keep language consistent within each paragraph — do not mix languages mid-paragraph.
Versioning
- Every
SKILL.mdhas ametadata.versionfield in YAML frontmatter (semver). - Bump the version once per commit, not per edit. Patch for fixes, minor for new content or restructuring.
README Maintenance
- When adding, removing, or renaming a skill, update
README.mdaccordingly:- Update the directory tree in the "目录结构" section.
- Update the skill list in the "当前 Skills" section (one-line description per skill).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.