From f7f0fcfd212d31a4b920a2bfb3b8057016427b22 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Jan 2026 23:55:22 +0000 Subject: [PATCH] Add comprehensive doc spec for Claude Code skills Create a world-class document type definition for Claude Code skill files that provides detailed guidance on: - Skill types (meta-skills, step skills, standalone) - File structure with YAML frontmatter and markdown content - Description writing best practices for search discoverability - Instruction organization with progressive disclosure - Hook configuration (Stop, PreToolUse, UserPromptSubmit) - Quality validation loops with promise tag pattern - Input/output specification with document type references - Work branch conventions for context accumulation - Completion patterns for workflows vs standalone skills - Common patterns and anti-patterns to avoid - Complete worked examples This spec enables consistent, high-quality skill definitions that AI agents can reliably execute. --- .deepwork/doc_specs/claude_skill_spec.md | 639 +++++++++++++++++++++++ 1 file changed, 639 insertions(+) create mode 100644 .deepwork/doc_specs/claude_skill_spec.md diff --git a/.deepwork/doc_specs/claude_skill_spec.md b/.deepwork/doc_specs/claude_skill_spec.md new file mode 100644 index 00000000..f58aa8a4 --- /dev/null +++ b/.deepwork/doc_specs/claude_skill_spec.md @@ -0,0 +1,639 @@ +--- +name: "Claude Code Skill Definition" +description: "Markdown files that define slash commands for Claude Code AI agents" +path_patterns: + - ".claude/skills/*/SKILL.md" + - ".claude/skills/*/*.md" +target_audience: "AI agents executing skills, developers creating custom workflows, DeepWork skill generator" +frequency: "Generated by `deepwork sync` from job.yml specifications, or manually authored for custom skills" +quality_criteria: + - name: Descriptive Name + description: "Name must be lowercase with dots separating job and step (e.g., `commit.test`, `deepwork_jobs.define`). Single-word names for meta-skills (e.g., `commit`)." + - name: Search-Friendly Description + description: "Description must be under 100 characters, specific about capabilities, action-oriented. Avoid vague terms like 'helps with' or meta-language like 'Trigger:', 'Keywords:'." + - name: Clear Goal Statement + description: "Instructions section must start with a clear **Goal** statement that tells the agent exactly what to accomplish." + - name: Structured Instructions + description: "Instructions must use headers, numbered lists for sequential steps, and bullets for options. Keep core instructions under 500 lines; use supplementary files for details." + - name: Complete Input Specification + description: "All required inputs must be documented: user parameters (what to gather) and file inputs from previous steps (what to read)." + - name: Explicit Output Requirements + description: "Outputs section must list all files the skill produces with clear filenames or paths. Use document type references when applicable." + - name: Measurable Quality Criteria + description: "Quality criteria must be verifiable, outcome-focused, and actionable. Agent should be able to self-evaluate against each criterion." + - name: Valid Hook Configuration + description: "Hooks in frontmatter must use correct structure: `hooks..[].hooks.[].type` with valid types (`prompt` or `command`)." + - name: Proper Workflow Continuation + description: "For multi-step workflows, completion section must specify next step invocation using the Skill tool. Standalone skills indicate they can be re-run anytime." + - name: Reference File Documentation + description: "Must include reference to source files (job.yml, instruction files) at the end for traceability." +--- + +# Claude Code Skill Definition + +A **skill** is a markdown file that defines a slash command for Claude Code. Skills provide AI agents with structured instructions to execute complex, multi-step tasks. When users type `/skill_name` in Claude Code, the agent reads the skill file and follows its instructions. + +## Key Concepts + +### Skill Types + +| Type | Naming Pattern | Purpose | Example | +|------|----------------|---------|---------| +| **Meta-skill** | `job_name` | Entry point for multi-step workflows | `commit`, `deepwork_jobs` | +| **Step skill** | `job_name.step_id` | Individual step in a workflow | `commit.test`, `deepwork_jobs.define` | +| **Standalone skill** | Any name | Independent utility, not part of workflow | `format_code`, `check_security` | + +### Generation vs. Manual Authoring + +Most skills are **generated** by DeepWork from job.yml specifications using Jinja2 templates: +``` +job.yml (specification) → SkillGenerator → SKILL.md (generated) +``` + +Custom skills can be **manually authored** for specialized needs not covered by job definitions. + +## File Structure + +Skills are markdown files with YAML frontmatter. Location: `.claude/skills//SKILL.md` + +```markdown +--- +name: skill_name +description: "Brief, search-friendly description" +user-invocable: true|false +hooks: + Stop: + - hooks: + - type: prompt|command + prompt: "..." + command: "..." +--- + +# skill_name + +**Step X/Y** in **job_name** workflow (or **Standalone skill**) + +> Brief job summary + +## Prerequisites (if dependencies exist) +... + +## Instructions +**Goal**: What this skill accomplishes + +[Detailed step-by-step instructions] + +## Required Inputs +... + +## Work Branch +... + +## Outputs +... + +## Quality Validation +... + +## On Completion +... + +--- +**Reference files**: `path/to/job.yml`, `path/to/instructions.md` +``` + +## Frontmatter Fields + +### Required Fields + +| Field | Type | Description | Example | +|-------|------|-------------|---------| +| `name` | string | Skill identifier (lowercase, dots for hierarchy) | `commit.test` | +| `description` | string | Brief description for search results (<100 chars) | `"Run the test suite until all tests pass"` | + +### Optional Fields + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `user-invocable` | boolean | `true` | If `false`, skill only invoked by other skills, not directly by user | +| `hooks` | object | none | Lifecycle hook configurations (see Hooks section) | + +## Instruction Writing Guidelines + +### Description Best Practices + +The description appears in Claude Code's skill search results. Make it findable: + +```yaml +# Good descriptions +description: "Run the test suite until all tests pass" +description: "Extract text from PDFs, fill forms, merge documents" +description: "Create job.yml specification from workflow requirements" + +# Bad descriptions (avoid) +description: "Helps with testing" # Too vague +description: "Trigger: test; Keywords: pytest, ci" # Meta-language +description: "This skill will assist users in..." # Verbose, passive +``` + +### Instruction Structure + +1. **Goal statement first** - Clear, one-line statement of what the skill accomplishes +2. **Progressive disclosure** - Essential info in main content, details in supplementary files +3. **Numbered steps** - Use numbered lists for sequential processes +4. **Concrete file paths** - Reference specific paths, not "the config file" +5. **Expected outcomes** - Describe what success looks like + +### Content Organization + +```markdown +## Instructions + +**Goal**: [One clear sentence describing the outcome] + +### Step 1: [Action] +[Instructions for first step] + +### Step 2: [Action] +[Instructions for second step] + +### Handling Edge Cases +[What to do when things go wrong] +``` + +### Keeping Skills Concise + +- Core instructions: **under 500 lines** +- Use supplementary files for detailed examples, templates, or reference material +- Reference supplementary files with full paths from project root +- Include examples in collapsible `
` blocks when lengthy + +## Hook Configuration + +Claude Code supports three lifecycle hooks for quality validation and automation. + +### Available Hook Events + +| Event | Trigger | Use Case | +|-------|---------|----------| +| `Stop` | Agent finishes responding | Quality validation loops | +| `PreToolUse` | Before tool execution | Security checks, input validation | +| `UserPromptSubmit` | User submits a prompt | Context injection, session setup | + +### Hook Structure + +```yaml +hooks: + Stop: + - hooks: + - type: prompt + prompt: | + Evaluate whether all quality criteria are met. + If met, respond: {"ok": true} + If not, respond: {"ok": false, "reason": "..."} + - type: command + command: ".deepwork/jobs/job_name/hooks/validate.sh" +``` + +### Hook Types + +| Type | Description | When to Use | +|------|-------------|-------------| +| `prompt` | LLM evaluates criteria using provided prompt | Nuanced quality judgments, subjective criteria | +| `command` | Shell script executes | Objective checks (tests, lint, format) | + +### Quality Validation Loop Pattern + +The Stop hook enables iterative refinement: + +1. Agent completes response +2. Stop hook evaluates quality criteria +3. If criteria not met → agent continues working +4. Loop repeats until all criteria satisfied + +**Implementation:** + +```yaml +hooks: + Stop: + - hooks: + - type: prompt + prompt: | + ## Quality Criteria + 1. All tests pass + 2. Code follows style guide + 3. Documentation updated + + Review the conversation. If ALL criteria met and + `✓ Quality Criteria Met` tag present, + respond: {"ok": true} + + Otherwise respond: + {"ok": false, "reason": "**AGENT: TAKE ACTION** - [criteria failed]"} +``` + +### Promise Tag Pattern + +The `` tag signals that the agent believes it has met all quality criteria: + +```markdown +## Quality Validation + +**Criteria (all must be satisfied)**: +1. Tests are passing +2. Code is properly formatted +3. Changes are reviewed + +**To complete**: Include `✓ Quality Criteria Met` in your final response only after verifying ALL criteria are satisfied. +``` + +## Input Specification + +### User Parameters + +Information gathered from the user before starting: + +```markdown +## Required Inputs + +**User Parameters** - Gather from user before starting: +- **market_segment**: The market segment to analyze (e.g., "enterprise SaaS") +- **competitor_count**: Number of competitors to identify (default: 5-7) +``` + +**Important**: When a skill has user inputs, instructions MUST tell the agent to "ask structured questions using the AskUserQuestion tool" - never use generic phrasing like "ask the user". + +### File Inputs from Previous Steps + +Files produced by earlier steps in the workflow: + +```markdown +**Files from Previous Steps** - Read these first: +- `competitors_list.md` (from `identify_competitors`) +- `research_notes.md` (from `research_competitors`) +``` + +## Output Specification + +### Simple Outputs + +```markdown +## Outputs + +**Required outputs**: +- `competitors_list.md` +- `research/notes.md` +``` + +### Outputs with Document Type References + +When outputs have defined document types (doc specs): + +```markdown +**Required outputs**: +- `positioning_report.md` + **Document Type**: Strategic Positioning Report + > Analysis of competitive positioning with recommendations + **Definition**: `.deepwork/doc_specs/positioning_report.md` + **Target Audience**: Product leadership, strategy teams + **Quality Criteria**: + 1. **Market Context**: Includes market size and growth trends + 2. **Competitor Matrix**: Side-by-side comparison of top 5 competitors + 3. **Recommendations**: Actionable positioning recommendations +``` + +## Work Branch Convention + +All workflow execution happens on dedicated Git branches: + +```markdown +## Work Branch + +Use branch format: `deepwork/job_name-[instance]-YYYYMMDD` + +- If on a matching work branch: continue using it +- If on main/master: create new branch with `git checkout -b deepwork/job_name-[instance]-$(date +%Y%m%d)` +``` + +This enables: +- Context accumulation across steps +- Resumability if interrupted +- Clean separation from main branch +- Easy review before merging + +## Completion Patterns + +### Step Skills (Non-Final) + +```markdown +## On Completion + +1. Verify outputs are created +2. Inform user: "Step 2/4 complete, outputs: research_notes.md" +3. **Continue workflow**: Use Skill tool to invoke `/job_name.next_step` +``` + +### Final Step Skills + +```markdown +## On Completion + +1. Verify outputs are created +2. Inform user: "Step 4/4 complete, outputs: final_report.md" +3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch. +``` + +### Standalone Skills + +```markdown +## On Completion + +1. Verify outputs are created +2. Inform user: "skill_name complete, outputs: output.md" + +This standalone skill can be re-run anytime. +``` + +## Meta-Skill Structure + +Meta-skills are entry points for multi-step workflows. They don't contain detailed instructions but route to appropriate starting steps. + +```markdown +--- +name: commit +description: "Run tests, lint, and commit code changes" +--- + +# commit + +**Multi-step workflow**: Run tests, lint, and commit code changes + +> A workflow for preparing and committing code changes with quality checks. + +## Available Steps + +1. **test** - Pull latest code and run the test suite until all tests pass +2. **lint** - Format and lint code with ruff (requires: test) +3. **commit_and_push** - Verify changed files, commit, and push (requires: lint) + +## Execution Instructions + +### Step 1: Analyze Intent + +Parse any text following `/commit` to determine user intent: +- "test" or related terms → start at `commit.test` +- Default → start at `commit.test` + +### Step 2: Invoke Starting Step + +Use the Skill tool to invoke the identified starting step: +``` +Skill tool: commit.test +``` + +### Handling Ambiguous Intent + +If user intent is unclear, use AskUserQuestion to clarify with available steps. + +## Context Files + +- Job definition: `.deepwork/jobs/commit/job.yml` +``` + +## Quality Criteria Patterns + +### Measurable Criteria + +Criteria should be objectively verifiable: + +```markdown +**Criteria (all must be satisfied)**: +1. All tests pass (exit code 0) +2. No lint errors (ruff check returns clean) +3. Coverage above 80% (measured by pytest-cov) +4. All imports are used (no unused imports) +``` + +### Outcome-Focused Criteria + +Focus on what the output achieves, not process steps: + +```markdown +**Criteria (all must be satisfied)**: +1. Report contains executive summary under 200 words +2. At least 5 competitors analyzed with 3+ data points each +3. Competitive matrix includes pricing, features, and market position +4. Recommendations are actionable with specific next steps +``` + +### Self-Evaluation Criteria + +Agent should be able to verify each criterion: + +```markdown +**Criteria (all must be satisfied)**: +1. **User Understanding**: Asked structured questions to gather requirements +2. **Complete Specification**: job.yml contains all required fields +3. **Valid Dependencies**: No circular references, file inputs match dependencies +4. **File Created**: job.yml exists at `.deepwork/jobs/[job_name]/job.yml` +``` + +## Common Patterns + +### Using Sub-Agents for Context Efficiency + +For steps that may generate lots of output, use sub-agents: + +```markdown +### Process + +Use a sub-agent for the lint operation to reduce context usage: + +1. Launch Task agent to handle linting +2. Sub-agent runs `ruff check --fix` and `ruff format` +3. Sub-agent reports results back +4. Continue workflow based on results +``` + +### Handling Dependencies + +```markdown +## Prerequisites (Verify First) + +Before proceeding, confirm these steps are complete: +- `/job_name.step_one` +- `/job_name.step_two` + +If prerequisites are not met, inform the user which steps must run first. +``` + +### Error Recovery + +```markdown +### If Tests Fail + +1. Analyze failure messages +2. Identify root cause +3. Fix the issue (implementation or test) +4. Re-run tests +5. Iterate until all tests pass +``` + +## Anti-Patterns to Avoid + +### Vague Instructions + +```markdown +# Bad +Do some research on competitors. + +# Good +Research each competitor in the list. For each competitor, gather: +1. Company overview (founding year, size, funding) +2. Product offerings (main products, pricing tiers) +3. Market positioning (target customers, unique value proposition) +``` + +### Missing Outputs + +```markdown +# Bad +## Outputs +Create a report with your findings. + +# Good +## Outputs +**Required outputs**: +- `competitors_list.md` - List of 5-7 competitors with descriptions +- `research/` - Directory containing per-competitor markdown files +``` + +### Generic Quality Criteria + +```markdown +# Bad +Criteria: +- Output is good +- User is satisfied + +# Good +Criteria: +1. List contains 5-7 competitors (not more, not less) +2. Each competitor entry includes: name, website, description, value proposition +3. No duplicate competitors +4. Selection rationale explains why each was chosen +``` + +### Process-Focused Instead of Outcome-Focused + +```markdown +# Bad +Criteria: +1. Ran the search command +2. Read the files +3. Wrote output + +# Good +Criteria: +1. Output file contains all required sections +2. Data is accurate and current (within last 12 months) +3. Analysis includes actionable recommendations +``` + +## Complete Example: Step Skill + +```markdown +--- +name: commit.test +description: "Pull latest code and run the test suite until all tests pass" +user-invocable: false +hooks: + Stop: + - hooks: + - type: prompt + prompt: | + Verify the tests are passing: + 1. Latest code was pulled from the branch + 2. Test command was correctly identified + 3. All tests pass (exit code 0) + + If ALL criteria met and `` tag present: {"ok": true} + Otherwise: {"ok": false, "reason": "**AGENT: TAKE ACTION** - [issue]"} +--- + +# commit.test + +**Step 1/3** in **commit** workflow + +> Run tests, lint, and commit code changes + +## Instructions + +**Goal**: Run the test suite and fix any failures until all tests pass + +### Step 1: Pull Latest Code + +```bash +git pull origin +``` + +Resolve any merge conflicts before proceeding. + +### Step 2: Detect Test Command + +Auto-detect based on project type: +- Python: `pytest`, `uv run pytest` +- Node.js: `npm test`, `yarn test` +- Go: `go test ./...` + +Check `pyproject.toml`, `package.json`, etc. for hints. + +### Step 3: Run Tests + +Execute the test command and capture output. + +### Step 4: Fix Failures + +If tests fail: +1. Analyze failure messages +2. Identify root cause +3. Fix implementation or test +4. Re-run tests +5. Iterate until passing + +## Work Branch + +Use branch format: `deepwork/commit-[instance]-YYYYMMDD` + +## Outputs + +**Required outputs**: +- Passing test suite (verified by exit code 0) + +## Quality Validation + +**Criteria (all must be satisfied)**: +1. Latest code was pulled from the branch +2. Test command was correctly identified +3. All tests pass + +**To complete**: Include `✓ Quality Criteria Met` after verifying ALL criteria. + +## On Completion + +1. Verify all tests pass +2. Inform user: "Step 1/3 complete, all tests passing" +3. **Continue workflow**: Use Skill tool to invoke `/commit.lint` + +--- + +**Reference files**: `.deepwork/jobs/commit/job.yml`, `.deepwork/jobs/commit/steps/test.md` +``` + +## Reference Documentation + +- **Claude Code Skills**: https://docs.anthropic.com/en/docs/claude-code/skills +- **Claude Code Hooks**: https://docs.anthropic.com/en/docs/claude-code/hooks +- **Prompting Best Practices**: https://www.anthropic.com/engineering/claude-code-best-practices +- **DeepWork Architecture**: `doc/architecture.md` +- **Hook System Details**: `doc/platforms/claude/hooks_system.md`