A small Agent Skills–compatible CLI that discovers skills generically, asks Claude Sonnet to match a request using metadata only, activates only the selected instructions, and generates the final response.
The implementation follows the Agent Skills progressive-disclosure lifecycle:
- Discover — scan
.skills/*/SKILL.mdand retain validated frontmatter metadata. - Match — send only skill
nameanddescriptionplus the user prompt to Claude. - Activate — read full instruction bodies only for selected skills.
- Execute — call Claude again with only active instructions.
- Enforce — apply generic machine-readable response contracts, including the exact
welcome-meheader.
- Node.js 20 or newer
- An Anthropic API key
npm ciSet the assignment-requested environment variable:
# macOS / Linux
export CLAUDE_API_KEY="your-key"
# Windows PowerShell
$env:CLAUDE_API_KEY="your-key"Run the CLI with one command (it builds automatically):
npm start -- "I'm new to this project. What should I do first?"The standard ANTHROPIC_API_KEY variable is also accepted. The default model is claude-sonnet-5; override it with CLAUDE_MODEL or --model if needed.
Prompts can also come from stdin after a build:
npm run build
echo "Generate release notes from: feat: add SSO; fix: prevent duplicate invoices" | node dist/cli.js --debugRun npm link after building if you want the mini-agent executable available on your path.
Welcome flow — must print the exact required header as its first line:
npm start -- --debug "I'm new to this project—please welcome me"Registry skill activation:
npm start -- --debug "Turn these commits into a customer changelog: feat: add SSO; fix: prevent duplicate invoices"
npm start -- --debug "Design a distinctive landing page for a neighborhood astronomy club"Negative-match proof — welcome-me should not activate:
npm start -- --debug "What's the weather today?"--debug writes selected skill names to stderr, keeping stdout clean for piping. Skill discovery can be inspected without an API key:
npm start -- --list-skillsnpm run check
npm run validate:skillsThe test suite verifies metadata-only matching, lazy instruction activation, unknown-selection filtering, unrelated-prompt isolation, exact header enforcement, and duplicate-prefix prevention. Tests use a fake Claude gateway and do not require an API key.
Claude performs semantic matching from the catalog rather than hard-coded keywords. Its selection response is constrained by a JSON Schema whose enum contains only discovered skill names. Runtime validation still deduplicates selections and drops unknown names defensively.
This intentionally costs two Claude calls per prompt: a small routing call and a generation call. That tradeoff makes the progressive-disclosure boundary explicit and easy to inspect.
welcome-me declares this spec-valid metadata extension:
metadata:
command-code-required-output-prefix: ">Welcome to our Command Code assignment agent!"The executor enforces that contract for any active skill that declares it. There is no skill-name check in the runtime, so arbitrary spec-compliant skills still work generically while the assignment's exact first-line requirement is deterministic.
Discovery validates the current Agent Skills constraints for names, descriptions, directory matching, supported frontmatter fields, compatibility length, and string metadata. Invalid skills are skipped with diagnostics.
Skill bodies are trusted project configuration. A production agent should add workspace trust controls before activating skills from an unfamiliar repository.
.
├── .skills/ # welcome-me + two attributed registry skills
├── src/
│ ├── agent.ts # select → activate → generate → enforce
│ ├── claude.ts # Anthropic SDK gateway
│ ├── cli.ts # arguments, stdin, output, debug mode
│ ├── matching.ts # metadata-only Sonnet router
│ ├── skills.ts # discovery, validation, activation
│ └── validate-skills.ts # standalone validation command
├── test/ # offline unit/integration tests
├── ATTRIBUTIONS.md
└── SUBMISSION.md