Skills Portfolio Scaffold

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

/
├── 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.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:

| 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.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//.git
git push -u origin main

Step 8: Add skills incrementally

Each new skill:

1. Create skills//SKILL.md with frontmatter
2. Create skills//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:

| Requirement | Where | Notes | |---|---|---| | SKILL.md with frontmatter | skills//SKILL.md | name, description, version minimum | | README.md | skills//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/
• 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://.github.io//

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: THEROCKSSS
• Source: THEROCKSSS/hermes-skills-portfolio
• License: MIT

Install and usage instructions live in the source repository linked above.