Files

Michal 56735a5290 docs: skills + revisions + proposals reference, plus cheatsheet update

Phase 7 of the Skills + Revisions + Proposals work — documentation
pass for the surface added in PR-1 through PR-6. Reference material
only; no code changes.

## What's added

- `docs/skills.md` — skill model, scoping rules, CLI surface, the
  `mcpctl config claude --project` setup flow, metadata schema (with
  the deferred-execution note for hooks/mcpServers/postInstall), the
  on-disk state file shape, atomic install mechanics, failure
  semantics, and what's deferred.
- `docs/revisions.md` — ResourceRevision model, semver auto-bump
  rules, contentHash diff key (cross-resource sync), CLI for history
  / diff / restore, RBAC, audit emission, storage growth note.
- `docs/proposals.md` — ResourceProposal model, the reviewer flow
  (CLI + web UI), atomic-approval mechanics, the propose_prompt /
  propose_skill MCP tools, the propose-learnings global skill that
  steers Claude toward engaging with them, and the deferred legacy
  PromptRequest cutover.

## What's edited

- Top-level `CLAUDE.md` — resource cheatsheet adds `skill`, `proposal`,
  `revision` with cross-references to the new docs. The legacy
  `promptrequest` entry stays (still on the legacy code path) but
  notes that new work should use `proposal`.

## What's NOT in this PR

- The PromptRequest → ResourceProposal cutover migration. Both run
  side-by-side today; the focused cutover PR will rename + backfill +
  drop. Keeping that out of PR-7 means review can stay on docs.
- Bundle-backup / `mcpctl apply -f` skill support (deferred from PR-3).
- `metadata.hooks` / `metadata.mcpServers` / `metadata.postInstall`
  execution (deferred from PR-5).
- Existing-page UI migration to Tailwind (deferred from PR-6 — old
  inline-styled pages coexist fine inside the new Layout).

These are tracked as future PRs; each is its own focused change.

## Verification

`pnpm test:run` whole monorepo: 162 test files / 2157 tests green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-07 17:58:04 +01:00

2.3 KiB

Raw Blame History

Claude Code Instructions

Task Master AI Instructions

Import Task Master's development workflow commands and guidelines, treat as if import is in the main CLAUDE.md file. @./.taskmaster/CLAUDE.md

Skill routing

When the user's request matches an available skill, ALWAYS invoke it using the Skill tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. The skill has specialized workflows that produce better results than ad-hoc answers.

Key routing rules:

Product ideas, "is this worth building", brainstorming → invoke office-hours
Bugs, errors, "why is this broken", 500 errors → invoke investigate
Ship, deploy, push, create PR → invoke ship
QA, test the site, find bugs → invoke qa
Code review, check my diff → invoke review
Update docs after shipping → invoke document-release
Weekly retro → invoke retro
Design system, brand → invoke design-consultation
Visual audit, design polish → invoke design-review
Architecture review → invoke plan-eng-review
Save progress, checkpoint, resume → invoke checkpoint
Code quality, health check → invoke health

Resource types

mcpctl resource cheatsheet:

server — MCP server definition
instance — running container (immutable, replicas-managed)
secret / secretbackend — credentials
template — reusable server blueprint
project — workspace grouping servers, prompts, agents
llm — server-managed LLM provider (api key + endpoint)
agent — LLM persona pinned to one Llm; project attach surfaces project Prompts as system context, project MCP servers as tools, and exposes the agent itself as an MCP virtual server (agent-<name>/chat). See docs/agents.md, docs/chat.md.
prompt / promptrequest — curated content / legacy pending proposal (use proposal for new work).
skill — Claude Code skill bundle (SKILL.md + files + typed metadata). Materialised onto disk by mcpctl skills sync. See docs/skills.md.
proposal — generic pending proposal queue, replaces promptrequest. Covers both prompts and skills. See docs/proposals.md. Triage via mcpctl review.
revision — append-only audit + diff log shared by prompts and skills. Auto-bumps semver on save. See docs/revisions.md.
rbac — access control bindings
mcptoken — bearer credentials for HTTP-mode mcplocal

2.3 KiB Raw Blame History

Claude Code Instructions

Task Master AI Instructions

Skill routing

Resource types

2.3 KiB

Raw Blame History