agentleFS
THEROCKSSSTHEROCKSSS/hermes-skills-portfolio/skills/skills-portfolio-scaffold/SKILL.md

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

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
  1. Distinctive:

    Every skill gets one of three tiers at publish time:

    line 97
  2. Very specific:

    Create .github/workflows/validate.yml (or .forgejo/workflows/validate.yml for Forgejo):

    line 120
  3. Very specific:

    Create skills/<skill-name>/SKILL.md with frontmatter

    line 162
  4. Very specific:

    Create skills/<skill-name>/README.md (Hallmark quality)

    line 163
  5. Very specific:

    Add an entry to skills-index.json

    line 164
  6. Distinctive:

    Every skill in the portfolio must have:

    line 170
  7. Very specific:

    Search with keyboard shortcut (/)

    line 184
  8. Very specific:

    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.

    line 211
  9. Very specific:

    Tier inflation: Don't mark everything core.

    line 213
  10. Distinctive:

    No categories: Every skill must belong to a category.

    line 214
  11. Distinctive:

    Invented usage data: Start all usage counts at 0.

    line 215
  12. Very specific:

    docs/ vs site/ drift: When you update site files, always copy them to docs/ too.

    line 217

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 install to work for end users)
  • Skills to publish — at least one SKILL.md with 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.js

Step 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:

TierMeaning
coreBroadly empowering, nearly any user benefits
featuredHighly useful within a category
utilityUseful 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.json on 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
          done

Step 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 main

Step 8: Add skills incrementally

Each new skill:

  1. Create skills/<skill-name>/SKILL.md with frontmatter
  2. Create skills/<skill-name>/README.md (Hallmark quality)
  3. Add an entry to skills-index.json
  4. Commit and push
  5. The CI validates the frontmatter

Skill Entry Requirements

Every skill in the portfolio must have:

RequirementWhereNotes
SKILL.md with frontmatterskills/<name>/SKILL.mdname, description, version minimum
README.mdskills/<name>/README.mdWhat it does, install, how to use, example
Index entryskills-index.jsonname, 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, Esc close detail, t toggle theme

GitHub Pages deployment

GitHub Pages only serves from / or /docs. Deploy:

  1. Copy site files + skills-index.json into docs/
  2. Settings → Pages → Source → Deploy from branch → main → /docs
  3. 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

  1. 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.
  2. Relative links in README. Links like ../other-skill/ break when a skill is published to its own repo via skill-publish. Use absolute URLs for cross-skill references.
  3. Tier inflation. Don't mark everything core. If all skills are core, the tier is meaningless. Reserve core for skills that nearly any user benefits from.
  4. No categories. Every skill must belong to a category. Uncategorized skills break the filter UI and the agent-parseable index.
  5. 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.
  6. skills-index.json too 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.
  7. docs/ vs site/ drift. When you update site files, always copy them to docs/ too. The docs/ directory is what GitHub Pages serves. Use a sync script or the portfolio-upkeep skill.

Verification Checklist

  • skills-index.json validates against skills-index.schema.json and every skill directory under skills/ has a matching index entry
  • Every skill entry has a tier (core/featured/utility) and a category, and not everything is tagged core
  • site/ files are mirrored into docs/ (what GitHub Pages actually serves)
  • The CI validation workflow runs and fails a skill missing name: in its frontmatter
  • All usage counts in newly added entries start at 0 — no fabricated install/star numbers

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.