Skip to content
Skills Library
Programming · Writing

fai-comment-tutorial

/fai-comment-tutorial

Auto-generate code tutorials from comments and docstrings — narrative walkthroughs with runnable examples. Use this skill when turning code into a learning guide, building onboarding docs, or producing example-driven documentation — even if the user only says "explain how this works".

Repository
frootai ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Auto-generate code tutorials from comments and docstrings — narrative walkthroughs with runnable examples. Use this skill when turning code into a learning guide, building onboarding docs, or producing example-driven documentation — even if the user only says "explain how this works".

Triggers from the description

explain how this works
Original author description

Auto-generate code tutorials from comments and docstrings — narrative walkthroughs with runnable examples. Use this skill when turning code into a learning guide, building onboarding docs, or producing example-driven documentation — even if the user only says "explain how this works".

How it works

  1. Overview
  2. Parameters
  3. Steps
  4. Output
  5. WAF Alignment
  6. Error Handling
  7. Usage
  8. Configuration Reference
  9. Monitoring
  10. Troubleshooting
Original SKILL.md headings · 153 lines, 651 words
SKILL.md preview
---
name: fai-comment-tutorial
description: Auto-generate code tutorials from comments and docstrings — narrative walkthroughs with runnable examples. Use this skill when turning code into a learning guide, building onboarding docs, or producing example-driven documentation — even if the user only says "explain how this works".
---

# Fai Comment Tutorial

Generates educational code comments explaining complex logic for learning and onboarding.

## Overview

This skill provides a structured, repeatable procedure for generates educational code comments explaining complex logic for learning and onboarding.. It can be used standalone as a LEGO block or auto-wired inside solution plays via the FAI Protocol.

**Category:** General
**Complexity:** Medium
**Estimated Time:** 10-30 minutes

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `target` | string | Yes | — | Target resource, file, or endpoint |
| `environment` | enum | No | `dev` | Target environment: `dev`, `staging`, `prod` |
| `verbose` | boolean | No | `false` | Enable detailed output logging |
| `dry_run` | boolean | No | `false` | Validate without making changes |
| `config_path` | string | No | `config/` | Path to configuration directory |

## Steps

### Step 1: Validate Prerequisites

Verify all required tools, credentials, and dependencies are available.

```bash
# Check required tools
command -v node >/dev/null 2>&1 || { echo 'Node.js required'; exit 1; }
command -v az >/dev/null 2>&1 || { echo 'Azure CLI required'; exit 1; }
```

### Step 2: Load Configuration

Read settings from the FAI manifest and TuneKit config files.

```bash
# Load from fai-manifest.json if inside a play
CONFIG_DIR="${config_path:-config}"
if [ -f "fai-manifest.json" ]; then
  echo "FAI Protocol detected — auto-wiring context"
fi
```

### Step 3: Execute Core Logic

Perform the primary operation: generates educational code comments explaining complex logic for learning and onboarding..

### Step 4: Validate Results

Verify the output meets quality thresholds and WAF compliance.

```bash
# Validate output
if [ "$?" -eq 0 ]; then
  echo "✅ Skill completed successfully"
else
  echo "❌ Skill failed — check logs"
  exit 1
fi
```

## Output

| Output | Type | Description |
|--------|------|-------------|
| `status` | enum | `success`, `warning`, `failure` |
| `duration_ms` | number | Execution time in milliseconds |
| `artifacts` | string[] | List of generated/modified files |
| `logs` | string | Detailed execution log |

## WAF Alignment

| Pillar | How This Skill Contributes |
|--------|---------------------------|
| reliability | Includes retry logic, validates outputs, provides rollback steps |
| operational-excellence | Produces structured logs, integrates with CI/CD, follows IaC patterns |

## Error Handling

| Exit Code | Meaning | Action |
|-----------|---------|--------|
| 0 | Success | Proceed to next step |
| 1 | Validation failure | Check input parameters |
| 2 | Dependency missing | Install required tools |
| 3 | Runtime error | Check logs, retry with `--verbose` |

## Usage

### Standalone

```bash
# Run this skill directly
npx frootai skill run fai-comment-tutorial
```

### Inside a Solution Play

When referenced in `fai-manifest.json`, this skill auto-wires with the play's context:

```json
{
  "primitives": {
    "skills": ["skills/fai-comment-tutorial/"]
  }
}
```

### Via Agent Invocation

Agents can invoke this skill using the `/skill` command in Copilot Chat.

## Configuration Reference

```json
{
  "skill": "skill-name",
  "version": "1.0.0",
  "timeout_seconds": 300,
  "retry_attempts": 3,
  "log_level": "info"
}
```

## Monitoring

Track skill execution metrics:

| Metric | Description | Alert Threshold |
|--------|-------------|----------------|
| Duration | Execution time | > 60 seconds |
| Success rate | Pass/fail ratio | < 95% |
| Error count | Failed executions | > 5/hour |

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| Timeout | Slow dependency | Increase timeout_seconds |
| Auth failure | Expired credentials | Refresh Managed Identity |
| Missing config | No fai-manifest.json | Create manifest or pass config_path |
| Validation error | Invalid input | Check parameter types and ranges |

## Notes

- This skill follows the FAI SKILL.md specification
- All outputs are deterministic when `dry_run=true`
- Integrates with FAI Engine for automated pipeline execution
- Part of the General category in the FAI primitives catalog
Files in this package (3)
  • SKILL.lean.md 4 KB
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB

Versions

The database has no other skills named fai-comment-tutorial.

Database snapshot: 13.11.2026 · package version 6fa071e0b458 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100build-docs
    Guide for building documentation and validating docstrings. Use this when asked to build docs, check docstrings, or validate documentation.
  • 90docs-guidelines
    General documentation guidelines that apply across all languages. Use this when writing or reviewing comments, docstrings, or doc headers in any code.
  • 90code-comments
    Full comment and docstring policy for this repo — what to delete, what to keep compressed, what to never touch, and the two local traps. Use when writing, reviewing, or pruning comments and docstrings in any language.
  • 100code-comments
    Extract comment locations from code files for analysis. Use when cleaning comments, auditing documentation, or analyzing comment patterns across languages.
  • 100make-program-tutorial
    Manual invocation only; use only when the user explicitly requests `make-program-tutorial` by exact name, OR when the user asks to use a skill to create an SDK/API/library tutorial. Create a clear, reproducible, step-by-step tutorial for a specific API/SDK/library (or a set of…
  • 100wise-code-comments
    Code-comment rules for EVERY comment and docstring written on the user's behalf in ANY programming language. ALWAYS consult this skill before writing, rewriting, or reviewing a code comment, docstring, or inline annotation - whether adding comments to new code, editing code that…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.