# Skills Portfolio Scaffold

> 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".

- **Type:** Skill
- **Install:** `agentstack add skill-therocksss-hermes-skills-portfolio-skills-portfolio-scaffold`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [THEROCKSSS](https://agentstack.voostack.com/s/therocksss)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [THEROCKSSS](https://github.com/THEROCKSSS)
- **Source:** https://github.com/THEROCKSSS/hermes-skills-portfolio/tree/main/skills/skills-portfolio-scaffold

## Install

```sh
agentstack add skill-therocksss-hermes-skills-portfolio-skills-portfolio-scaffold
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```json
{
  "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):

```yaml
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

```bash
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](https://github.com/THEROCKSSS)
- **Source:** [THEROCKSSS/hermes-skills-portfolio](https://github.com/THEROCKSSS/hermes-skills-portfolio)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-therocksss-hermes-skills-portfolio-skills-portfolio-scaffold
- Seller: https://agentstack.voostack.com/s/therocksss
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.