feat(skills): add bundled Box productivity skill

[iskysun96]

Add skills/productivity/box/ — a Hermes-native bundled Box skill with CCG service-account auth, CLI-first agent workflows, REST fallback, and SDK development reference. Includes tests and .env.example CCG block. No MCP integration, no upstream sync, no website doc changes.

What does this PR do?

Adds a bundled Box productivity skill so Hermes can manage Box content via CLI and REST — uploads, folders, search, shared links, webhooks, Box AI, bulk operations, and troubleshooting.

Hermes acts as the app's service account (Client Credentials Grant), not the human user. Setup uses a free Box Developer Console Platform App → BOX_CLIENT_ID / BOX_CLIENT_SECRET / BOX_ENTERPRISE_ID in ~/.hermes/.env → box configure:environments:add … --ccg-auth. Free developer accounts auto-authorize CCG apps.

This follows the footprint ladder (skill + docs, no new core tools). No MCP catalog entry; agents use terminal with Box CLI.

Related Issue

Fixes #

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• skills/productivity/box/SKILL.md — bundled skill (HARDLINE format, CCG-first, CLI tool ladder, reference router)
• skills/productivity/box/references/auth-and-setup.md — CCG app creation, CLI env wiring, service-account content model
• skills/productivity/box/references/cli-guide.md — --json, --fields, serial execution, box request
• skills/productivity/box/references/content-workflows.md — files, folders, upload/download, links, collaborations
• skills/productivity/box/references/search-and-ai.md — search, metadata-query, Box AI CLI
• skills/productivity/box/references/bulk-operations.md — inventory-plan-execute-verify for batch ops
• skills/productivity/box/references/webhooks-and-events.md — webhooks and events patterns
• skills/productivity/box/references/rest-api.md — curl fallback when CLI unavailable
• skills/productivity/box/references/sdk-development.md — SDK auth and app development path
• skills/productivity/box/references/troubleshooting.md — 401/403/404/409/429, actor mismatches
• skills/productivity/box/templates/ccg-config.json.example — template for box configure:environments:add
• tests/skills/test_box_skill.py — frontmatter, description length, no MCP, reference path invariants
• .env.example — isolated commented CCG Box block

How to Test

1. Run skill tests:

   scripts/run_tests.sh tests/skills/test_box_skill.py

2. Confirm skill is listed:

   hermes skills list | grep -i box

3. Optional live CCG + CLI path (requires free Box Developer Platform App with CCG):

   npm install -g @box/cli

   Add credentials to ~/.hermes/.env:

   BOX_CLIENT_ID=your-client-id
   BOX_CLIENT_SECRET=your-client-secret
   BOX_ENTERPRISE_ID=your-enterprise-id
   

   Copy and fill skills/productivity/box/templates/ccg-config.json.example, then:

   box configure:environments:add /path/to/ccg-config.json --ccg-auth --name hermes --set-as-current
   box users:get me --json --fields id,name,login
   box folders:items 0 --json --max-items 5 --fields id,name,type

4. Optional end-to-end skill prompt:

   hermes --toolsets skills -q "Use the box skill to verify CCG auth and list the service account root folder"

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — platforms: [linux, macos, windows]
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

For New Skills

• This skill is broadly useful to most users (if bundled) — Box works with a free Developer account; CCG auto-authorizes on dev accounts
• SKILL.md follows the standard format (frontmatter, trigger conditions, steps, pitfalls)
• No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools) — requires user-installed @box/cli (Node.js), documented in prerequisites
• I've tested the skill end-to-end: hermes --toolsets skills -q "Use the box skill to verify CCG auth" — requires live Box CCG app

Screenshots / Logs

N/A

[hbkwong]

Thinking about parity on this one. Should we also add BOX_CLIENT_ID/BOX_CLIENT_SECRET/BOX_ENTERPRISE_ID to OPTIONAL_ENV_VARS in hermes_cli/config.py? Looks like other platforms register theirs with category="skill" (my understanding is that they'd surface in hermes setup)

[teknium1]

Thanks for the detailed CCG/access model and for addressing the earlier setup-registration and flag-form command feedback. Current main does not contain a Box skill, so this remains a useful contribution, but the current shape needs rework before landing.

Problems

• skills/productivity/box/SKILL.md:20-27 makes Node 18+, globally installed @box/cli, and Box credentials the primary path in an always-on bundled skill. AGENTS.md:867-868 places heavy-dependency or niche skills in optional-skills/; AGENTS.md:902-914 also says new skill prose must not make a third-party CLI its headline interaction surface.
• skills/productivity/box/SKILL.md:5 credits community, but AGENTS.md:926-931 requires the external contributor's real name and GitHub handle first.
• tests/skills/test_box_skill.py:15-32,79-143 freezes names and literal documentation strings rather than testing durable contracts, contrary to AGENTS.md:1309-1356.

Suggested changes

• Move this to optional-skills/productivity/box; tools/skills_hub.py:3158-3174 already supports official opt-in skills.
• Credit Chris Kim (@iskysun96) in frontmatter.
• Replace snapshot assertions with frontmatter/link/template validation invariants, and keep Box CLI detail progressively disclosed rather than the primary skill surface.

Automated hermes-sweeper review.

[teknium1]

author: community conflicts with AGENTS.md:926-931, which requires an external skill to credit the human contributor first. Please use the contributor's real name and GitHub handle (Chris Kim / @iskysun96).

[teknium1]

This makes a globally installed third-party CLI the required primary path for an always-on skill. AGENTS.md:867-868 directs heavy-dependency or niche skills to optional-skills/, and AGENTS.md:902-914 says third-party CLIs must not be the headline surface of new skill prose. Please re-scope this as an opt-in skill and restructure the entrypoint around native Hermes tooling.

[teknium1]

This fixed file inventory, together with the forbidden-name and literal-command assertions below, is a change-detector snapshot: routine documentation restructuring will fail CI without proving a broken contract. Replace these with durable frontmatter, link-resolution, and template-validation invariants.

[teknium1]

Merged via PR #85767 — your commit was cherry-picked onto current main with your authorship preserved in git log, plus a small compliance-polish commit on top (frontmatter conventions, docs registration). The skill ships bundled at skills/productivity/box/ as discussed. Thanks for the deep iteration on the OAuth flow and reference structure!