skills-portfolio-scaffold
Skill1 starsChanged 4 months agoMITView on GitHub
Use when a user wants to publish their own Hermes skills as a categorized, ranked, sortable skills portfolio — discoverable by both humans (sortable site) and agents (structured index) — or says "set up a skills portfolio" / "make my skills installable".
- Commits and pushes
In this repository58 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- api-test-suiteSkill
- ascii-artSkill
- caddy-reverse-proxySkill
- changelog-generatorSkill
- color-palette-generatorSkill
- cron-taskSkill
- csv-toolkitSkill
- discord-bot-buildSkill
- docker-umbrellaSkill
- dotfiles-manageSkill
- email-sendSkill
- env-config-managerSkill
- excalidraw-diagramSkill
- file-organizerSkill
- forgejo-self-hostSkill
- frontend-design-toolkitSkill
- generate-dockerfileSkill
- gif-searchSkill
- git-backupSkill
- github-actions-ciSkill
- hallmark-readmeSkill
- http-api-testerSkill
- invoice-generatorSkill
- json-formatterSkill
- log-analyzerSkill
- markdown-linterSkill
- markdown-to-pdfSkill
- markdown-to-slidesSkill
- mcp-server-buildSkill
- media-id-mappingSkill
- movie-catalogue-siteSkill
- movie-night-calendarSkill
- ntfy-notifierSkill
- ocr-documentsSkill
- ollama-localSkill
- openapi-generatorSkill
- password-generatorSkill
- pdf-extractSkill
- portfolio-upkeepSkill
- qr-code-generatorSkill
- regex-testerSkill
- resume-builderSkill
- rss-monitorSkill
- searxng-self-hostSkill
- skill-publishSkill
- skill-registry-catalogSkill
- snippet-managerSkill
- sqlite-dashboardSkill
- streaming-provider-embedsSkill
- tailscale-deploySkill
- telegram-bot-buildSkill
- tmdb-metadataSkill
- uptime-kuma-self-hostSkill
- watchlist-syncSkill
- webhook-receiverSkill
- youtube-transcriptSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 4 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 97
Every skill gets one of three tiers at publish time:
- Very specific: line 120
Create .github/workflows/validate.yml (or .forgejo/workflows/validate.yml for Forgejo):
- Very specific: line 162
Create skills/<skill-name>/SKILL.md with frontmatter
- Very specific: line 163
Create skills/<skill-name>/README.md (Hallmark quality)
- Very specific: line 164
Add an entry to skills-index.json
- Distinctive: line 170
Every skill in the portfolio must have:
- Very specific: line 184
Search with keyboard shortcut (/)
- Very specific: line 211
Index drift: If you add a skill directory but forget to add an entry to skills-index.json, the site won't show it and the CI should warn.
- Very specific: line 213
Tier inflation: Don't mark everything core.
- Distinctive: line 214
No categories: Every skill must belong to a category.
- Distinctive: line 215
Invented usage data: Start all usage counts at 0.
- Very specific: line 217
docs/vssite/drift: When you update site files, always copy them to docs/ too.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
skills-portfolio-scaffold
Overview
Scaffold a skills portfolio repository with the three-surface architecture: a monorepo of skills, a skills-index.json for agent-parseable metadata, a sortable static site, and CI validation. This is the meta-skill that reproduces the portfolio structure for anyone who wants to publish their own skills — under their own name and branding, never a clone of this one.
When to Use
- The user wants to publish their own Hermes skills as a portfolio.
- The user wants a structured, categorized, ranked collection of skills (not just a flat directory).
- The user wants their skills to be discoverable by both humans (sortable site) and agents (structured index).
- The user says "set up a skills portfolio", "I want to publish my skills", or "make my skills installable".
Prerequisites
- Git installed and configured
- A GitHub account (for the public shopfront)
- Hermes Agent installed (for
hermes skills installto work for end users) - Skills to publish — at least one
SKILL.mdwith frontmatter
Workflow
Step 0: Name the portfolio
Before scaffolding anything, ask the user for three things: what they want their portfolio called (e.g. "Jane's Automation Skills," not "Hermes Skills Portfolio" — this is their shopfront, not a copy of this one), their name or handle as it should appear in the README/site footer, and a one-sentence tagline. Use their answers everywhere portfolio.name / portfolio.owner / portfolio.tagline appear in Step 2 — never leave a placeholder value or default to "Hermes" in the generated output.
Step 1: Create the repo structure
<portfolio-name>/
├── README.md ← the shopfront (Hallmark quality)
├── skills-index.json ← single source of truth
├── skills-index.schema.json ← schema for the index
├── LICENSE ← MIT recommended
├── .gitignore
├── docs/adr/ ← architecture decisions
├── skills/ ← one directory per skill
│ └── <skill-name>/
│ ├── SKILL.md
│ └── README.md
└── site/ ← sortable static site
├── index.html
├── styles.css
└── app.jsStep 2: Create skills-index.json
The index is the single source of truth. Both the README and the static site render from it. Schema:
{
"version": "1.0.0",
"generated_at": "ISO-8601 timestamp",
"portfolio": {
"name": "Your Portfolio Name",
"owner": "Your Name",
"tagline": "One sentence. No filler.",
"total_skills": 0,
"github_url": "https://github.com/your-user/your-portfolio"
},
"categories": {
"devops": { "name": "DevOps", "description": "...", "skill_count": 0 },
"frontend": { "name": "Frontend", "description": "...", "skill_count": 0 }
},
"skills": [
{
"name": "skill-name",
"category": "devops",
"tier": "core",
"description": "One line. What agent + skill delivers.",
"install_url": "https://github.com/your-user/your-portfolio/blob/main/skills/skill-name/SKILL.md",
"path": "skills/skill-name",
"usage": { "hub_installs": 0, "github_clones": 0, "stars": 0 },
"recency": "2026-01-01",
"source": "new",
"source_attribution": ""
}
]
}Step 3: Assign usefulness tiers
Every skill gets one of three tiers at publish time:
| Tier | Meaning |
core | Broadly empowering, nearly any user benefits |
featured | Highly useful within a category |
utility | Useful for specific workflows |
This is a curated judgment, not a metric. It's the day-one ranking — usage data enriches it later but never replaces it.
Step 4: Create the static site
The site/ directory contains a self-contained HTML/CSS/JS app that:
- Fetches
skills-index.jsonon page load - Renders skill cards in a responsive grid
- Supports sorting (tier-then-usage default, plus usage/recency/category/alphabetical)
- Supports filtering (category, tier) and search
- Uses OKLCH colors, a real font pairing, no AI-slop patterns
See the portfolio's own site/ directory for a working reference implementation.
Step 5: Add CI validation
Create .github/workflows/validate.yml (or .forgejo/workflows/validate.yml for Forgejo):
name: validate
on: push
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate SKILL.md frontmatter
run: |
for skill_md in skills/*/SKILL.md; do
name=$(grep -m1 '^name:' "$skill_md" | sed 's/^name:[[:space:]]*//')
[ -z "$name" ] && echo "FAIL: $skill_md missing name" && exit 1
doneStep 6: Write the README
The portfolio README is the shopfront. It should include:
- A one-sentence tagline (no filler)
- Install instructions for individual skills
- A categories table
- The ranking explanation (tiers + usage)
- The repo structure
- Links to ADRs (if any)
- License info
Step 7: Publish
git init
git add -A
git commit -m "Initial portfolio scaffold"
git remote add origin https://github.com/<user>/<portfolio-name>.git
git push -u origin mainStep 8: Add skills incrementally
Each new skill:
- Create
skills/<skill-name>/SKILL.mdwith frontmatter - Create
skills/<skill-name>/README.md(Hallmark quality) - Add an entry to
skills-index.json - Commit and push
- The CI validates the frontmatter
Skill Entry Requirements
Every skill in the portfolio must have:
| Requirement | Where | Notes |
SKILL.md with frontmatter | skills/<name>/SKILL.md | name, description, version minimum |
README.md | skills/<name>/README.md | What it does, install, how to use, example |
| Index entry | skills-index.json | name, category, tier, description, install_url, path, source |
Site Features
The portfolio static site includes:
- Dark mode default with light toggle (localStorage persistence)
- Sortable skill cards (by tier+usage, usage, recency, category, alphabetical)
- Category and tier filters with filter chips
- Search with keyboard shortcut (
/) - Detail page overlay: clicking a skill opens a full page with:
- "What it does" (user-facing description)
- "How an agent uses it" (agent-facing use cases)
- SKILL.md tab (raw markdown rendered for reading)
- README tab (raw markdown rendered for reading)
- Install command with copy-to-clipboard
- Close button (X icon), Esc key, click-outside-to-close
- Shareable URL hash:
#skill/<name>
- Category distribution bar
- Back-to-top button
- Toast notifications
- Keyboard:
/search,Escclose detail,ttoggle theme
GitHub Pages deployment
GitHub Pages only serves from / or /docs. Deploy:
- Copy site files + skills-index.json into
docs/ - Settings → Pages → Source → Deploy from branch →
main→/docs - Site live at
https://<username>.github.io/<repo-name>/
skills-index.json enrichment
Each skill entry should include agent_use, user_use, skillmd_content, and readme_content fields so the detail page can show all content without fetching individual files.
Common Pitfalls
- Index drift. If you add a skill directory but forget to add an entry to
skills-index.json, the site won't show it and the CI should warn. Keep them in sync. - Relative links in README. Links like
../other-skill/break when a skill is published to its own repo viaskill-publish. Use absolute URLs for cross-skill references. - Tier inflation. Don't mark everything
core. If all skills are core, the tier is meaningless. Reservecorefor skills that nearly any user benefits from. - No categories. Every skill must belong to a category. Uncategorized skills break the filter UI and the agent-parseable index.
- Invented usage data. Start all usage counts at 0. Don't fabricate install numbers — they'll be overwritten by real data once the portfolio has traffic, and fake numbers erode trust.
skills-index.jsontoo large. Embedding full SKILL.md and README.md content in the index makes it large (500KB+ for 50 skills). This is acceptable for a static site — it loads once and enables instant detail page rendering without per-skill fetches.docs/vssite/drift. When you update site files, always copy them todocs/too. Thedocs/directory is what GitHub Pages serves. Use a sync script or the portfolio-upkeep skill.
Verification Checklist
skills-index.jsonvalidates againstskills-index.schema.jsonand every skill directory underskills/has a matching index entry- Every skill entry has a
tier(core/featured/utility) and acategory, and not everything is taggedcore site/files are mirrored intodocs/(what GitHub Pages actually serves)- The CI validation workflow runs and fails a skill missing
name:in its frontmatter - All
usagecounts in newly added entries start at 0 — no fabricated install/star numbers
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.

