hr-skills-maintaining
Skill58 starsChanged 2 months agoMITView on GitHub
Repository-level skill describing metadata, directory structure, workflows, and conventions for the hr-skills monorepo. Use this skill when validating, creating, editing, or maintaining HR skill packages, including SKILL.md, content/, prompts/, and examples/.
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- biomeSkill
- bunSkill
- changesetSkill
- clackSkill
- dry-refactoringSkill
- github-awesome-copilot-git-commitSkill
- hr-root-router-maintainingSkill
- humanizerSkill
- jscpdSkill
- markdownSkill
- pdfSkill
- skill-vetterSkill
- turboSkill
- typescriptSkill
- valibotSkill
- hr-skillsSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 10 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 83
Verify directory structure and file organization
- Distinctive: line 86
Verify internal relative links
- Distinctive: line 91
Keep repository documentation synchronized with repository changes
- Very specific: line 137
Always include a SKILL.md in every skill package.
- Very specific: line 138
Keep SKILL.md concise and focused on activation, tasks, prompts, and guidance.
- Distinctive: line 142
Avoid duplicating information across supporting documents.
- Distinctive: line 150
Keep each document focused on a single responsibility.
- Distinctive: line 151
Prefer reusable HR knowledge over organization-specific content.
- Distinctive: line 152
Use descriptive headings instead of long paragraphs.
- Distinctive: line 154
Keep prompt libraries easy to browse and maintain.
- Distinctive: line 155
Use realistic HR scenarios in workflow examples.
- Distinctive: line 156
Keep repository documentation synchronized whenever a skill changes.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill 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
HR Skills repository guide
This skill defines the repository-wide conventions for the hr-skills monorepo. It helps AI assistants and contributors consistently create, validate, edit, and maintain skill packages.
Each skill is stored in its own directory under skills/ and must contain a SKILL.md. Supporting documentation may be added through content/, prompts/, and examples/, each serving a distinct purpose.
Repository structure
Each skill lives under skills/hr-<name>/.
skills/hr-<name>/
├── SKILL.md # Required
├── content/ # Optional
│ └── <name>.md
├── prompts/ # Optional
│ └── <topic>.md
└── examples/ # Optional
└── <scenario>.mdFile responsibilities
Each file has a single responsibility.
SKILL.mddefines activation behavior, supported tasks, prompt summaries, repository metadata, and usage guidance.content/contains detailed reference documentation, concepts, frameworks, terminology, and best practices.prompts/stores reusable prompt libraries grouped by a single HR topic.examples/demonstrates realistic end-to-end HR workflows and business scenarios.
Supporting files should complement each other instead of repeating the same information.
Content quality standards
- HR-domain only — prompts and guidance must cover HR-specific patterns and best practices, not generic management or business advice.
- No obvious content — avoid widely-known basics. Focus on nuanced guidance that HR professionals actually need AI assistance with.
SKILL.mdis for AI agents — be concise; context window is a shared resource. Assume the agent is smart; only include what it doesn't already know. Use progressive disclosure —SKILL.mdis an overview, not an exhaustive manual.- Trigger phrases matter — the
descriptionfield determines when a skill activates. Include specific, realistic HR trigger phrases like "Write a PIP", "Conduct a stay interview", "Analyze turnover".
Checklist before publishing a skill
Core quality
descriptionis specific and includes key HR trigger phrasesdescriptioncovers both what the skill does and when to use itSKILL.mdbody is under 500 lines- Prompts are grouped by meaningful subtopics
- No time-sensitive information (laws, tools, versions)
- Consistent HR terminology throughout
- Prompts use
[placeholders]for variable inputs - Each subtopic has 4-7 focused prompts
- Tips section provides actionable professional guidance
Frontmatter
namematches the skill directory name exactlydescriptionis wrapped in a single pair of double quotes, with trigger phrases as plain comma-separated text (not individually quoted)metadata.authoris set toTuan Duc Tranmetadata.versionis set
Structure
## Supported taskslists 8-12 concrete tasks## Key promptsis divided into logical subtopic sections## Tipshas 4-6 professional best-practice tips
Supported tasks
- Explain repository conventions, workflows, and directory structure
- Validate skill packages against repository standards
- Scaffold new skills following repository conventions
- Review and improve
SKILL.md - Review and improve
content/,prompts/, andexamples/ - Validate frontmatter and naming conventions
- Verify directory structure and file organization
- Detect duplicated content across files
- Validate Markdown formatting and repository rules
- Verify internal relative links
- Generate contributor guidance
- Produce release and pre-publish checklists
- Generate Conventional Commit messages
- Recommend CI commands using Bun and Turbo
- Keep repository documentation synchronized with repository changes
Key prompts
Repository management
- "Explain the repository structure and file responsibilities."
- "Describe the workflow for creating a new HR skill."
- "Summarize the repository conventions contributors should follow."
- "List the validation commands required before opening a pull request."
- "Explain the differences between
SKILL.md,content/,prompts/, andexamples/."
Skill validation
- "Review this skill package against repository standards."
- "Validate this
SKILL.mdand list every issue." - "Check whether this skill follows naming conventions."
- "Identify duplicated content across all supporting documents."
- "Validate Markdown formatting and internal links."
Skill scaffolding
- "Scaffold a complete HR skill package."
- "Generate a new
SKILL.mdfollowing repository conventions." - "Create a matching
content/,prompts/, andexamples/structure." - "Generate missing supporting documents for an existing skill."
- "Create repository-compliant frontmatter."
Content and prompt management
- "Review this reference document for completeness."
- "Generate a reusable prompt library for this HR topic."
- "Organize these prompts into logical categories."
- "Remove duplicated prompts already summarized in
SKILL.md." - "Recommend where content should belong within the skill package."
Contributor assistance
- "Generate a Conventional Commit message."
- "Create a pull request checklist."
- "Generate a GitHub Actions workflow for repository validation."
- "Explain how to add a new skill from start to finish."
- "Review this pull request for repository consistency."
Tips
- Always include a
SKILL.mdin every skill package. - Keep
SKILL.mdconcise and focused on activation, tasks, prompts, and guidance. - Store conceptual documentation in
content/. - Store reusable prompt collections in
prompts/. - Store realistic business workflows in
examples/. - Avoid duplicating information across supporting documents.
- Name directories and files using kebab-case.
- Files inside
content/should omit thehr-prefix (for example,skills/hr-kpi/content/kpi.md). - Organize prompt libraries around a single HR topic.
- Validate Markdown formatting, naming conventions, and internal links before committing.
Best practices
- Keep each document focused on a single responsibility.
- Prefer reusable HR knowledge over organization-specific content.
- Use descriptive headings instead of long paragraphs.
- Cross-reference related documents rather than duplicating information.
- Keep prompt libraries easy to browse and maintain.
- Use realistic HR scenarios in workflow examples.
- Keep repository documentation synchronized whenever a skill changes.
Common mistakes
- Putting long conceptual documentation inside
SKILL.md. - Duplicating prompts between
SKILL.mdandprompts/. - Mixing multiple unrelated topics in one prompt library.
- Using inconsistent skill or directory names.
- Naming
content/files with thehr-prefix. - Forgetting to update internal links after renaming files.
- Creating examples without realistic business context.
- Allowing supporting documents to become inconsistent with
SKILL.md.
Naming conventions
| Item | Convention |
| Skill directory | skills/hr-kebab-case/ |
name field | Matches the directory name |
| Content file | Skill name without the hr- prefix |
| Prompt file | Descriptive kebab-case topic |
| Example file | Scenario-based kebab-case filename |
| Markdown headings | Follow sequential heading levels |
| Internal links | Always use relative paths |
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.

