OGT Docs Create

Create new documentation entities in the docs-first system. Routes to specialized creation sub-skills for tasks, definitions, rules, features, and social content. Use when adding any new documentation.

Security Scan

This is an instruction-only docs-creation helper that is internally consistent: it contains shell commands to create/seed documentation folders and files and does not request credentials, installs, or unrelated system access.

Purpose & Capability

The skill's name and description (create documentation entities) match the actions the SKILL.md instructs (mkdir, cp, echo, create task/feature/rule files). It does not request unrelated credentials, binaries, or config paths.

Instruction Scope

The SKILL.md tells the agent to run shell commands that create and modify files under docs/ and CHANGELOG.md (mkdir, cp, cat, echo, touch). This behavior is expected for a docs-creation tool, but it will modify the local filesystem and can overwrite files if used carelessly. The instructions reference docs/_templates which must exist; the agent will not validate that and will perform operations as-is.

Install Mechanism

No install spec or external downloads — instruction-only. Nothing is written to disk by an installer and no third-party packages are pulled in by the skill itself.

Credentials

The skill does not request environment variables, credentials, or config paths. The SKILL.md does not read unrelated env vars or secret paths.

Persistence & Privilege

always is false and the skill does not request persistent system presence or modify other skills' configuration. It will run shell commands when invoked, which is normal for this type of instruction-only skill.

Assessment

This skill is coherent with its stated purpose but it will execute shell commands that create and modify files in your repository (mkdir, cp, cat, echo, touch). Before using it: (1) review docs/_templates and the SKILL.md scripts to ensure they do what you expect, (2) run on a disposable branch or backup your repo to avoid accidental overwrites, (3) inspect batch scripts (they assume bash utilities like sed/tr/echo) before running, and (4) if you don't want an agent to modify files autonomously, restrict or review agent actions before they run these commands.

Root skill for creating new documentation entities.

Overview

This skill routes to specialized creation workflows based on what type of document you're creating. Every entity becomes a folder with appropriate files and signals.

flowchart TB
    CREATE["ogt-docs-create"] --> TASK["ogt-docs-create-task"]
    CREATE --> DEF["ogt-docs-define"]
    CREATE --> RULE["ogt-docs-rules"]
    CREATE --> SOCIAL["ogt-docs-create-social"]
    CREATE --> CHANGE["ogt-docs-changelog"]

    TASK --> |folder| PENDING["docs/todo/pending/"]
    DEF --> |folder| DEFINE["docs/define/"]
    RULE --> |folder| RULES["docs/rules/"]
    SOCIAL --> |folder| CONTENT["docs/content/"]
    CHANGE --> |file| CHANGELOG["CHANGELOG.md"]

When to Use

• Creating new tasks
• Adding definitions (features, code, business, etc.)
• Establishing new rules
• Creating social/marketing content
• Updating changelog

Quick Reference

Creating	Sub-Skill	Target
Task	ogt-docs-create-task	docs/todo/pending/
Feature	ogt-docs-define-feature	docs/define/features/
Business def	ogt-docs-define-business	docs/define/business/
Code def	ogt-docs-define-code	docs/define/code/
Marketing def	ogt-docs-define-marketing	docs/define/marketing/
Branding def	ogt-docs-define-branding	docs/define/branding/
Tool doc	ogt-docs-define-tools	docs/define/tools/
Code rule	ogt-docs-rules-code	docs/rules/code/
Git rule	ogt-docs-rules-git	docs/rules/git/
Social post	ogt-docs-create-social	docs/content/social/
Changelog	ogt-docs-changelog	CHANGELOG.md

---

Creation Workflow

All creation follows the same pattern:

flowchart LR
    A[Identify Type] --> B[Create Folder]
    B --> C[Copy Template]
    C --> D[Fill Content]
    D --> E[Add Signals]
    E --> F[Verify Structure]

Step 1: Identify Type

Determine what you're creating:

If you need to...	Create a...	Location
Track work to do	Task	docs/todo/pending/
Document a product feature	Feature	docs/define/features/
Document code architecture	Code definition	docs/define/code/
Establish coding standard	Code rule	docs/rules/code/
Record what changed	Changelog entry	CHANGELOG.md

Step 2: Create Folder

# Use slug format: lowercase, hyphens, no spaces
mkdir -p docs/{section}/{category}/{slug}

# Examples
mkdir -p docs/todo/pending/user-auth-flow
mkdir -p docs/define/features/dark-mode
mkdir -p docs/rules/code/error-handling

Step 3: Copy Template

# Copy appropriate template
cp docs/_templates/{type}.md docs/{path}/{slug}/{type}.md

# Examples
cp docs/_templates/task.md docs/todo/pending/user-auth-flow/task.md
cp docs/_templates/feature.md docs/define/features/dark-mode/feature.md
cp docs/_templates/rule.md docs/rules/code/error-handling/rule.md

Step 4: Fill Content

Edit the template with actual content. See sub-skill documentation for required sections.

Step 5: Add Signals

# Common signals
echo '{"schema": "1.0", "created": "'$(date -Iseconds)'"}' > {folder}/.version

# Type-specific signals
echo "high" > docs/todo/pending/{task}/.priority
touch docs/rules/code/{rule}/.enforced_by

Step 6: Verify Structure

# Verify folder has required files
ls -la docs/{path}/{slug}/

# Expected output example for task:
# task.md
# .version
# .priority

---

Templates Overview

Task Template

# Task: {Title}

## Summary

{What and why}

## Objectives

- Objective 1
- Objective 2

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Dependencies

{None or list}

## Estimated Effort

{Size} ({time})

Feature Template

# Feature: {Name}

## Summary

{What the feature does}

## User Stories

As a {user}, I want to {action}, so that {benefit}.

## Scope

### In Scope

- Item 1

### Out of Scope

- Item 1

## Success Metrics

- Metric 1

Definition Template

# {Name}

## Summary

{One paragraph}

## Details

{Full explanation}

## Examples

{Examples}

## Related

- {Links}

Rule Template

# Rule: {Name}

## Summary

{One sentence}

## Rationale

{Why}

## The Rule

{MUST/SHOULD/MAY statements}

## Examples

### Correct

{example}

### Incorrect

{example}

## Enforcement

{How enforced}

---

Batch Creation

Create multiple related items at once:

#!/bin/bash
# create-feature-with-tasks.sh

FEATURE=$1

# Create feature definition
mkdir -p docs/define/features/$FEATURE
cat > docs/define/features/$FEATURE/feature.md << EOF
# Feature: $(echo $FEATURE | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g')

## Summary

TODO: Add summary

## User Stories

As a user, I want to TODO, so that TODO.
EOF

# Create initial tasks
for task in "design" "implement" "test" "document"; do
  mkdir -p docs/todo/pending/${FEATURE}-${task}
  cat > docs/todo/pending/${FEATURE}-${task}/task.md << EOF
# Task: $(echo $FEATURE | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g') - $(echo $task | sed 's/\b\(.\)/\u\1/g')

## Summary

${task^} the $FEATURE feature.

## Objectives

- TODO

## Acceptance Criteria

- [ ] TODO
EOF
  echo "medium" > docs/todo/pending/${FEATURE}-${task}/.priority
done

echo "Created feature: $FEATURE"
echo "Created tasks: ${FEATURE}-design, ${FEATURE}-implement, ${FEATURE}-test, ${FEATURE}-document"

Usage:

./create-feature-with-tasks.sh dark-mode

---

Naming Conventions

Slug Format

All folder names use slug format:

Rule	Example
Lowercase	user-auth not User-Auth
Hyphens for spaces	dark-mode not dark_mode
No special chars	oauth2 not oauth2.0
Descriptive	steam-oauth-provider not sop
Under 30 chars	Keep it readable

Good Names

docs/todo/pending/add-steam-oauth
docs/define/features/dark-mode-toggle
docs/rules/code/no-implicit-any

Bad Names

docs/todo/pending/Add Steam OAuth          # Spaces, caps
docs/define/features/dark_mode_toggle      # Underscores
docs/rules/code/rule1                      # Not descriptive

---

Validation

After creating any document:

Check Required Files

# Task
test -f docs/todo/pending/{slug}/task.md || echo "MISSING: task.md"
test -f docs/todo/pending/{slug}/.priority || echo "MISSING: .priority"

# Feature
test -f docs/define/features/{slug}/feature.md || echo "MISSING: feature.md"
test -f docs/define/features/{slug}/mvp.md || echo "MISSING: mvp.md"

# Rule
test -f docs/rules/{category}/{slug}/rule.md || echo "MISSING: rule.md"
test -f docs/rules/{category}/{slug}/.enforced_by || echo "MISSING: .enforced_by"

Check Required Sections

# For any markdown file, check for required headings
file=$1
required=("## Summary" "## Objectives" "## Acceptance Criteria")

for section in "${required[@]}"; do
  grep -q "$section" "$file" || echo "MISSING: $section in $file"
done

---

Common Creation Patterns

New Feature Flow

1. Create feature definition
2. Create mvp.md defining scope
3. Create phase_0.md for initial work
4. Create tasks for phase_0

# 1. Feature folder
mkdir -p docs/define/features/search

# 2. Feature definition
cat > docs/define/features/search/feature.md << 'EOF'
# Feature: Global Search

## Summary
Fuzzy search across all content types.
EOF

# 3. MVP scope
cat > docs/define/features/search/mvp.md << 'EOF'
# MVP: Global Search

## In MVP
- Phase 0 only

## Definition of Done
- Search returns results in <100ms
- Fuzzy matching works
EOF

# 4. Phase 0
cat > docs/define/features/search/phase_0.md << 'EOF'
# Phase 0: Basic Search

## Deliverables
- MiniSearch integration
- Global search component
EOF

# 5. Tasks
mkdir -p docs/todo/pending/search-minisearch-setup
# ... create task

New Rule Flow

1. Identify pattern to standardize
2. Create rule folder
3. Write rule with examples
4. Configure enforcement
5. Announce to team

# 1. Rule folder
mkdir -p docs/rules/code/async-await

# 2. Rule definition
cat > docs/rules/code/async-await/rule.md << 'EOF'
# Rule: Prefer async/await

## Summary
SHOULD use async/await over .then() chains.

## Rationale
Improved readability and error handling.

## The Rule
...
EOF

# 3. Examples
cat > docs/rules/code/async-await/examples.md << 'EOF'
# Examples
...
EOF

# 4. Enforcement
echo "eslint prefer-async-await" > docs/rules/code/async-await/.enforced_by

# 5. Configure ESLint
# Edit .eslintrc.js

---

Signal Files Quick Reference

Signal	Used For	Content
.version	All	JSON schema version
.priority	Tasks	critical/high/medium/low
.enforced_by	Rules	List of tools
.status	Definitions	draft/review/approved
.created_at	All	ISO timestamp
.created_by	All	Author name

---

Creation Checklist

Before finalizing any created document:

• Folder uses slug format
• Primary file exists (task.md, feature.md, etc.)
• .version signal added
• Required sections present
• No TODO placeholders remain
• Links are valid
• Spelling/grammar checked
• Related documents cross-referenced